chore: enable selective docstring linting (ruff)

enable-docstring-linting.patch

@@ -0,0 +1,37 @@
+*** Begin Patch
+*** Update File: pyproject.toml
+@@
+- [tool.ruff.lint]
+- line-length = 100
+- [tool.ruff.lint]
+- # The D (doc) and DTZ (datetime zone) lint classes current heavily violated - fix later
+- select = ["ALL"]
+- ignore = [
+-     "CPY", # we do not require copyright in every file
+-     "D", # todo: docstring linting
+-     "D203",
+-     "D204",
+-     "D213",
+-     "DTZ", # To add
+-     # Linter does not detect when types are used for Pydantic
+-     "TC001",
+-     "TC003",
+- ]
++ [tool.ruff.lint]
++ line-length = 100
++ # Gradually enable docstring (D) checks: remove global ignore for "D"
++ # and keep specific D-codes ignored that are still noisy.
++ select = ["ALL"]
++ ignore = [
++     "CPY", # we do not require copyright in every file
++     # D (docstrings) — removed to enable most D-rules. We continue to ignore
++     # some specific D-codes that are currently noisy:
++     "D203",
++     "D204",
++     "D213",
++     "DTZ", # to add
++     # Linter does not detect when types are used for Pydantic
++     "TC001",
++     "TC003",
++ ]
+*** End Patch

pyproject.toml

@@ -52,15 +52,17 @@ show_missing=true
 line-length = 100
 
 [tool.ruff.lint]
-# The D (doc) and DTZ (datetime zone) lint classes current heavily violated - fix later
+# Gradually enable docstring (D) checks: remove global ignore for "D"
+# and keep specific D-codes ignored that are still noisy.
 select = ["ALL"]
 ignore = [
-    "CPY",  # we do not require copyright in every file
-    "D",  # todo: docstring linting
+    "CPY", # we do not require copyright in every file
+    # D (docstrings) — removed to enable most D-rules. We continue to ignore
+    # some specific D-codes that are currently noisy:
     "D203",
     "D204",
     "D213",
-    "DTZ", # To add
+    "DTZ", # to add
     # Linter does not detect when types are used for Pydantic
     "TC001",
     "TC003",

src/config.py

@@ -1,3 +1,8 @@
+"""Configuration management for the OpenML REST API.
+
+Handles loading and caching of configuration from TOML files and environment variables.
+"""
+
 import functools
 import logging
 import os
@@ -49,11 +54,13 @@ def _load_configuration(file: Path) -> TomlTable:
 
 
 def load_routing_configuration(file: Path = _config_file) -> TomlTable:
+    """Load routing configuration from the config file."""
     return typing.cast("TomlTable", _load_configuration(file)["routing"])
 
 
 @functools.cache
 def load_database_configuration(file: Path = _config_file) -> TomlTable:
+    """Load and cache database configuration with environment variable overrides."""
     configuration = _load_configuration(file)
     database_configuration = _apply_defaults_to_siblings(
         configuration["databases"],
@@ -78,4 +85,5 @@ def load_database_configuration(file: Path = _config_file) -> TomlTable:
 
 
 def load_configuration(file: Path = _config_file) -> TomlTable:
+    """Load configuration from a TOML file."""
     return tomllib.loads(file.read_text())

src/core/__init__.py

@@ -0,0 +1,4 @@
+"""Core utilities for the OpenML REST API.
+
+Includes error handling, data conversions, access control, and formatting.
+"""

src/core/access.py

@@ -1,3 +1,8 @@
+"""Access control utilities for the OpenML REST API.
+
+Provides functions to check user permissions and dataset access.
+"""
+
 from sqlalchemy.engine import Row
 
 from database.users import User, UserGroup

src/core/conversions.py

@@ -1,9 +1,17 @@
+"""Utilities for converting between string and numeric representations.
+
+Provides functions for recursive conversion of nested data structures.
+"""
+
 from collections.abc import Iterable, Mapping, Sequence
 from typing import Any
 
 
 def _str_to_num(string: str) -> int | float | str:
-    """Tries to convert the string to integer, otherwise float, otherwise returns the input."""
+    """Convert string to integer, float, or leave unchanged.
+
+    Attempts conversion in order: integer, float, then returns original string.
+    """
     if string.isdigit():
         return int(string)
     try:
@@ -13,8 +21,10 @@ def _str_to_num(string: str) -> int | float | str:
 
 
 def nested_str_to_num(obj: Any) -> Any:
-    """Recursively tries to convert all strings in the object to numbers.
-    For dictionaries, only the values will be converted."""
+    """Recursively convert all strings in object to numbers.
+
+    For dictionaries, only the values will be converted.
+    """
     if isinstance(obj, str):
         return _str_to_num(obj)
     if isinstance(obj, Mapping):
@@ -25,8 +35,10 @@ def nested_str_to_num(obj: Any) -> Any:
 
 
 def nested_num_to_str(obj: Any) -> Any:
-    """Recursively tries to convert all numbers in the object to strings.
-    For dictionaries, only the values will be converted."""
+    """Recursively convert all numbers in object to strings.
+
+    For dictionaries, only the values will be converted.
+    """
     if isinstance(obj, str):
         return obj
     if isinstance(obj, Mapping):
@@ -39,6 +51,7 @@ def nested_num_to_str(obj: Any) -> Any:
 
 
 def nested_remove_nones(obj: Any) -> Any:
+    """Recursively remove None values from nested data structures."""
     if isinstance(obj, str):
         return obj
     if isinstance(obj, Mapping):
@@ -53,6 +66,7 @@ def nested_remove_nones(obj: Any) -> Any:
 
 
 def nested_remove_single_element_list(obj: Any) -> Any:
+    """Recursively unwrap single-element lists in nested data structures."""
     if isinstance(obj, str):
         return obj
     if isinstance(obj, Mapping):