updata package

.github/workflows/testing.yml

@@ -33,7 +33,7 @@ jobs:
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip
-        python -m pip install -r requirements-github.txt  # Install dependencies from requirements.txt
+        python -m pip install -r requirements-gh-action.txt  # Install dependencies
 
     - name: Run tests with pytest
       run: |

.github/workflows/typing.yml

@@ -31,7 +31,7 @@ jobs:
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip
-        python -m pip install mypy
+        python -m pip install -r requirements-mypy.txt  # Install dependencies
 
     - name: Type check with mypy
       run: |

README.md

@@ -1,10 +1,19 @@
 # SuomiGeoData
 
 ## What is SuomiGeoData?
-SuomiGeoData is a Python package designed to simplify the process of downloading and extracting geospatial data from Suomi, that is Finland. The features of the package include:
+SuomiGeoData is a Python package whose concept originated on September 11, 2024. It is designed to simplify the process of downloading and extracting geospatial data from Suomi, that is Finland. The package offers the following features:
 
-- **[Paituli](https://paituli.csc.fi/download.html)** 
-  - Accessing the topographic database index map.
+
+* [Paituli](https://paituli.csc.fi/download.html) website
+
+    - Provides access to vector format index maps for downloading DEM and the topographic database.
+    - Downloads DEM as raster files and the topographic database as shapefiles based on label names from the index maps.
+
+
+## Roadmap
+
+* Enable downloading DEM for a specified area using a shapefile.
+* Enable downloading the topographic database for a specified area using a shapefile.
 
 
 ## Easy Installation
@@ -23,9 +32,16 @@ A brief example of how to start:
 >>> paituli = SuomiGeoData.Paituli()
 
 # get the topographic database index map
->>> im_tb = paituli.indexmap_tdb
->>> im_tb.shape
-(3132, 3)
+>>> paituli.indexmap_tdb.head()
+
+     label                                               path	                                         geometry
+    -------------------------------------------------------------------------------------------------------------
+0	K2344R	mml/maastotietokanta/2022/shp/K2/K23/K2344R.sh...	POLYGON ((104000 6606000, 104000 6618000, 1160...
+1	K2334R	mml/maastotietokanta/2022/shp/K2/K23/K2334R.sh...	POLYGON ((104000 6582000, 104000 6594000, 1160...
+2	K2343R	mml/maastotietokanta/2022/shp/K2/K23/K2343R.sh...	POLYGON ((104000 6594000, 104000 6606000, 1160...
+3	K2443L	mml/maastotietokanta/2022/shp/K2/K24/K2443L.sh...	POLYGON ((92000 6642000, 92000 6654000, 104000...
+4	K2443R	mml/maastotietokanta/2022/shp/K2/K24/K2443R.sh...	POLYGON ((104000 6642000, 104000 6654000, 1160...
+...
 ```
 
 ## Documentation

SuomiGeoData/__init__.py

@@ -6,4 +6,4 @@
 ]
 
 
-__version__ = '0.0.1'
+__version__ = '0.1.0'

SuomiGeoData/core.py

@@ -33,3 +33,36 @@ def is_valid_write_shape_driver(
             output = False
 
         return output
+
+    @property
+    def _url_prefix_paituli_dem_tdb(
+        self,
+    ) -> str:
+
+        '''
+        Returns the prefix url for downloading files
+        based on DEM and topographic database labels.
+        '''
+
+        output = 'https://www.nic.funet.fi/index/geodata/'
+
+        return output
+
+    @property
+    def default_http_headers(
+        self,
+    ) -> dict[str, str]:
+
+        '''
+        Returns the default http headers to be used for the web requests.
+        '''
+
+        output = {
+            'Accept': 'text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.7',
+            'User-Agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/128.0.0.0 Safari/537.36',
+            'Host': 'www.nic.funet.fi',
+            'Accept-Encoding': 'gzip, deflate, br, zstd',
+            'Connection': 'keep-alive'
+        }
+
+        return output

SuomiGeoData/paituli.py

@@ -1,27 +1,33 @@
 import os
+import io
+import zipfile
 import geopandas
+import requests
 import typing
 from .core import Core
 
 
 class Paituli:
 
     '''
-    Executes downloading and extracting data from Paituli (https://paituli.csc.fi/download.html).
+    Executes downloading and extracting data from Paituli
+    (https://paituli.csc.fi/download.html).
 
     Attributes:
     -----------
+    index_dem : GeoDataFrame
+        A GeoDataFrame containing the DEM index map.
+
     index_td : GeoDataFrame
-        A GeoDataFrame containing the topographical database index map.
+        A GeoDataFrame containing the topographic database index map.
     '''
 
     def __init__(
         self
     ) -> None:
 
         '''
-        Initializes the class by loading the GeoDataFrame of index maps for
-        DEM (raster data) and topographical database (vector data).
+        Initializes the class by loading the GeoDataFrame of index maps.
         '''
 
         # DEM index map
@@ -45,8 +51,7 @@ def save_indexmap_dem(
     ) -> bool:
 
         '''
-        Saves the GeoDataFrame of the DEM
-        index map to the specified file path.
+        Saves the GeoDataFrame of the DEM index map to the specified file path.
 
         Parameters
         ----------
@@ -185,3 +190,153 @@ def is_valid_label_tdb(
         '''
 
         return label in self.tdb_labels
+
+    def dem_download_by_labels(
+        self,
+        labels: list[str],
+        folder_path: str,
+        http_headers: typing.Optional[dict[str, str]] = None
+    ) -> bool:
+
+        '''
+        Downloads the DEM raster files for the given labels.
+
+        Parameters
+        ----------
+        labels : list of str
+            List of label names from the DEM index map.
+
+        folder_path : str
+            Complete folder path to save the downloaded raster files.
+
+        http_headers : dict, optional
+            HTTP headers to be used for the web request. If not provided, the default headers
+            :attr:`SuomiGeoData.core.Core.default_http_headers` will be used.
+
+        Returns
+        -------
+        bool
+            True if all the DEM raster files were successfully downloaded and
+            exist at the specified folder path, False otherwise.
+        '''
+
+        # check whether the input labels exist
+        for label in labels:
+            if self.is_valid_label_dem(label):
+                pass
+            else:
+                raise Exception(
+                    f'The label "{label}" does not exist in the index map.'
+                )
+
+        # check the existence of the given folder path
+        if os.path.isdir(folder_path):
+            pass
+        else:
+            raise Exception(
+                f'The folder path "{folder_path}" is not a valid directory.'
+            )
+
+        # web request headers
+        if http_headers is None:
+            headers = Core().default_http_headers
+        else:
+            headers = http_headers
+
+        # download topographic database
+        suffix_urls = self.indexmap_dem[self.indexmap_dem['label'].isin(labels)]['path']
+        count = 1
+        for label, url in zip(labels, suffix_urls):
+            label_url = Core()._url_prefix_paituli_dem_tdb + url
+            response = requests.get(
+                url=label_url,
+                headers=headers
+            )
+            label_file = os.path.join(
+                folder_path, f'{label}.tif'
+            )
+            with open(label_file, 'wb') as label_raster:
+                label_raster.write(response.content)
+            print(
+                f'Download of label {label} completed (count {count}/{len(labels)}).'
+            )
+            count = count + 1
+
+        output = all(os.path.isfile(os.path.join(folder_path, f'{label}.tif')) for label in labels)
+
+        return output
+
+    def tdb_download_by_labels(
+        self,
+        labels: list[str],
+        folder_path: str,
+        http_headers: typing.Optional[dict[str, str]] = None
+    ) -> bool:
+
+        '''
+        Downloads the topographic database folders of shapefiles for the given labels.
+
+        Parameters
+        ----------
+        labels : list of str
+            List of label names from the topographic database index map.
+
+        folder_path : str
+            Complete folder path to save the downloaded folder of shapefiles.
+
+        http_headers : dict, optional
+            HTTP headers to be used for the web request. If not provided, the default headers
+            :attr:`SuomiGeoData.core.Core.default_http_headers` will be used.
+
+        Returns
+        -------
+        bool
+            True if all the topographic database folders were successfully downloaded and
+            exist at the specified folder path, False otherwise.
+        '''
+
+        # check whether the input labels exist
+        for label in labels:
+            if self.is_valid_label_tdb(label):
+                pass
+            else:
+                raise Exception(
+                    f'The label "{label}" does not exist in the index map.'
+                )
+
+        # check the existence of the given folder path
+        if os.path.isdir(folder_path):
+            pass
+        else:
+            raise Exception(
+                f'The folder path "{folder_path}" is not a valid directory.'
+            )
+
+        # web request headers
+        if http_headers is None:
+            headers = Core().default_http_headers
+        else:
+            headers = http_headers
+
+        # download topographic database
+        suffix_urls = self.indexmap_tdb[self.indexmap_tdb['label'].isin(labels)]['path']
+        count = 1
+        for label, url in zip(labels, suffix_urls):
+            label_url = Core()._url_prefix_paituli_dem_tdb + url
+            response = requests.get(
+                url=label_url,
+                headers=headers
+            )
+            label_data = io.BytesIO(response.content)
+            with zipfile.ZipFile(label_data, 'r') as label_zip:
+                label_zip.extractall(
+                    os.path.join(folder_path, label)
+                )
+            print(
+                f'Download of label {label} completed (count {count}/{len(labels)}).'
+            )
+            count = count + 1
+
+        output = all(os.path.isdir(os.path.join(folder_path, label)) for label in labels)
+
+        return output

docs/changelog.rst

@@ -3,10 +3,37 @@ Release Notes
 =============
 
 
+Version 0.1.0
+-------------
+
+* **Release date:** 17-Sep-2024.
+
+* **Feature Additions:** 
+
+    * Access characteristics of the DEM index map.
+    * Download selected labels as raster files from the DEM index map.
+    * Download selected labels as shapefile folders from the topographic database index map.
+
+* **GitHub Actions Integration:**
+
+    * Linting with `flake8` to enforce PEP8 code formatting.
+    * Type checking with `mypy` to verify annotations throughout the codebase.
+    * Code testing with `pytest` to ensure code reliability.
+    * Test Coverage with **Codecov** to monitor and report test coverage.
+
+* **Compatibity:** Verified with Python 3.10, 3.11, and 3.12.
+
+* **Documentation:** Added new badges to `README.md` to display statuses for linting, type-checking, testing, and coverage.
+
+* **Development status:** Upgraded to Pre-Alpha from Planning.
+
+
 Version 0.0.1
 -------------
 
-* **Features:** Accessing the topographic database index map via the :class:`SuomiGeoData.Paituli` class.
+* **Release date:** 14-Sep-2024.
+
+* **Features:** Functionality for accessing the characteristics of topographic database index map.
 
 * **Development status:** Planning.
 

docs/index.rst

@@ -12,6 +12,7 @@ Welcome to SuomiGeoData's documentation!
 
    introduction
    installation
+   quickstart
    modules
    changelog