feat: add docstrings (#1)

* chore: modify library config

* chore: add licencecheck exceptions

* chore: add pre-commit to tox

* feat: add doctests to functions

* fix: change paths printing in doctests

Makefile

@@ -7,6 +7,7 @@ docs:
 	mkdocs serve --livereload -w quackosm
 
 test:
-	pytest -n auto
+	pytest --durations=20 --doctest-modules --doctest-continue-on-failure srai
+	pytest --durations=20 tests
 
 .PHONY: install docs test

docs/assets/css/docstrings.css

@@ -53,9 +53,16 @@ a.autorefs-external:hover::after {
 
 table.highlighttable td.linenos,
 span.linenos,
-.highlight .gp, .highlight .go {
+.highlight .gp,
+.highlight .go {
   user-select: none;
   -webkit-user-select: none;
   -moz-user-select: none;
   -ms-user-select: none;
 }
+
+.highlight code {
+  font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas,
+    "Liberation Mono", "Courier New", monospace, SFMono-Regular, Consolas, Menlo,
+    monospace;
+}

pyproject.toml

@@ -50,6 +50,7 @@ test = [
     "pytest-check",
     "pytest-parametrization",
     "pytest-xdist",
+    "pytest-doctestplus",
     "pyogrio",
     "srai>=0.6.2",
 ]
@@ -150,8 +151,13 @@ push = false
 addopts = ["--import-mode=importlib"]
 markers = ["slow: marks tests as slow (deselect with '-m \"not slow\"')"]
 log_cli = true
+doctest_optionflags = ['ELLIPSIS', 'NORMALIZE_WHITESPACE', 'IGNORE_EXCEPTION_DETAIL']
 
 [tool.licensecheck]
 using = "requirements"
 zero = false
 ignore_licenses = ["UNKNOWN"]
+ignore_packages = [
+    'docformatter',             # uses MIT license, has mismatched license in analysis
+    'mkdocs-jupyter',           # uses Apache-2.0 license, has mismatched license in analysis
+]

quackosm/conftest.py

@@ -0,0 +1,21 @@
+"""Fixtures for doctests."""
+
+import urllib.request
+from pathlib import Path
+
+import pytest
+
+LFS_DIRECTORY_URL = "https://github.com/kraina-ai/srai-test-files/raw/main/files/"
+
+
+@pytest.fixture(autouse=True)
+def add_pbf_files(doctest_namespace):  # type: ignore
+    """Download PBF files used in doctests."""
+    extracts = ["monaco", "kiribati", "maldives"]
+    download_directory = Path(__file__).parent / "files"
+    download_directory.mkdir(parents=True, exist_ok=True)
+    for extract_name in extracts:
+        pbf_file_download_url = LFS_DIRECTORY_URL + f"{extract_name}-latest.osm.pbf"
+        pbf_file_path = download_directory / f"{extract_name}.osm.pbf"
+        urllib.request.urlretrieve(pbf_file_download_url, pbf_file_path)
+        doctest_namespace[f"{extract_name}_pbf_path"] = pbf_file_path

quackosm/pbf_file_reader.py

@@ -138,8 +138,8 @@ def get_features_gdf(
             file_paths (Union[str, Path, Iterable[Union[str, Path]]]):
                 Path or list of paths of `*.osm.pbf` files to be parsed.
             explode_tags (bool, optional): Whether to split tags into columns based on OSM tag keys.
-                If `None`, will be set based on tags_filter parameter.
-                If no tags filter is provided, then explode_tags will set to `False`,
+                If `None`, will be set based on `tags_filter` parameter.
+                If no tags filter is provided, then `explode_tags` will set to `False`,
                 if there is tags filter it will set to `True`. Defaults to `None`.
             ignore_cache: (bool, optional): Whether to ignore precalculated geoparquet files or not.
                 Defaults to False.
@@ -198,8 +198,8 @@ def convert_pbf_to_gpq(
                 the geoparquet file. If not provided, will be generated based on hashes
                 from provided tags filter and geometry filter. Defaults to `None`.
             explode_tags (bool, optional): Whether to split tags into columns based on OSM tag keys.
-                If `None`, will be set based on tags_filter parameter.
-                If no tags filter is provided, then explode_tags will set to `False`,
+                If `None`, will be set based on `tags_filter` parameter.
+                If no tags filter is provided, then `explode_tags` will set to `False`,
                 if there is tags filter it will set to `True`. Defaults to `None`.
             ignore_cache (bool, optional): Whether to ignore precalculated geoparquet files or not.
                 Defaults to False.
@@ -1438,8 +1438,7 @@ def _parse_features_relation_to_groups(
 
         Args:
             features_relation (duckdb.DuckDBPyRelation): Generated features from the loader.
-            explode_tags (bool, optional): Whether to split tags into columns based on OSM tag keys.
-                Defaults to True.
+            explode_tags (bool): Whether to split tags into columns based on OSM tag keys.
 
         Returns:
             duckdb.DuckDBPyRelation: Parsed features_relation.

tox.ini

@@ -9,9 +9,13 @@ skip_missing_interpreters = True
 [testenv]
 groups =
     test
-deps = coverage
+deps =
+    coverage
+    pre-commit
 commands =
-    coverage run --source=quackosm -m pytest -v --durations=20 tests
+    coverage run --data-file=.coverage.doctests --source=quackosm -m pytest -v --durations=20 --doctest-modules --doctest-continue-on-failure quackosm
+    coverage run --data-file=.coverage.tests --source=quackosm -m pytest -v --durations=20 tests
+    coverage combine
     coverage xml -o coverage.{envname}.xml
     coverage report -m
 skip_install = true