feat(logging): report library warnings as log records

- 17 warnings.warn calls across 6 modules become _logger.warning
- auth.py keeps its DeprecationWarning, the one correct use left
- page_package.py gains the module logger it lacked
- tests assert on caplog instead of pytest.warns
- get-started.md notes that a warnings filter no longer applies

Author: LukasGold

docs/get-started.md

@@ -77,6 +77,12 @@ osw.set_log_level("DEBUG")    # see more
 osw.disable_logging()         # detach the handler osw attached
 ```
 
+Problems that osw can work around are WARNING records on the same logger, not
+Python `warnings`. A truncated query result and a page that does not exist are
+examples. A `warnings` filter or the `-W` option therefore has no effect on
+them. A message that repeats is also written out every time, where the warnings
+machinery would have shown it once. Use `set_log_level` to control them.
+
 The records go to `stderr`, which leaves `stdout` free for your program's own
 output. That matters for anything speaking a protocol over `stdout`, such as an
 MCP stdio server. Pass `osw.enable_logging(stream=...)` to send them elsewhere.

src/osw/controller/page_package.py

@@ -1,10 +1,10 @@
 import importlib.util
 import json
+import logging
 import re
 import sys
 from pathlib import Path
 from typing import Optional, Union
-from warnings import warn
 
 from opensemantic.v1 import OswBaseModel
 from pydantic.v1 import FilePath
@@ -17,6 +17,8 @@
 from osw.utils.regex import RegExPatternExtended
 from osw.wtsite import WtPage, WtSite
 
+_logger = logging.getLogger(__name__)
+
 # Definition of constants
 PATTERNS = {
     "Category string with prefix in quotes": RegExPatternExtended(
@@ -267,7 +269,7 @@ def find_first_package_dir(
             # expected: not every search path holds every package
             continue
         except ValueError as e:
-            warn(
+            _logger.warning(
                 f"Multiple elements {package_or_script_name} found in "
                 f"{search_path}: {e}"
             )
@@ -697,7 +699,7 @@ def recursive(
                 new_listed_pages = []
                 required_packages = []
                 if script_path is None:
-                    warn(
+                    _logger.warning(
                         f"Package script for {package_to_process} not found in any "
                         f"of the search paths: {search_paths}"
                     )
@@ -711,7 +713,7 @@ def recursive(
                             package_script
                         )
                     except Exception as e:
-                        warn(
+                        _logger.warning(
                             f"Error reading package script for "
                             f"{package_to_process}: {e}"
                         )
@@ -724,7 +726,7 @@ def recursive(
                 new_listed_pages = []
                 required_packages = []
                 if package_dir is None:
-                    warn(
+                    _logger.warning(
                         f"Package info for {package_to_process} not found in any "
                         f"of the search paths: {search_paths}"
                     )
@@ -738,7 +740,7 @@ def recursive(
                             get_required_packages_from_package_info_file(package_info)
                         )
                     except Exception as e:
-                        warn(
+                        _logger.warning(
                             f"Error reading package info for {package_to_process}: {e}"
                         )
             # Check for redundant pages
@@ -812,7 +814,7 @@ def recursive(
         # Report on redundantly listed pages
         for pg in rec_ret["redundant_pages"].keys():
             pks = rec_ret["redundant_pages"][pg]
-            warn(f"Page {pg} is listed in {len(pks)} packages!: {pks}")
+            _logger.warning(f"Page {pg} is listed in {len(pks)} packages!: {pks}")
         # Get all listed pages
         all_listed_pages = []
         for pck in rec_ret["listed_pages"].keys():

src/osw/core.py

@@ -11,7 +11,6 @@
 from enum import Enum
 from typing import Any, Dict, List, Optional, Type, Union, overload
 from uuid import UUID, uuid4
-from warnings import warn
 
 import black
 import datamodel_code_generator
@@ -286,7 +285,7 @@ def sort_list_of_entities_by_class(
                         f"as the class does not define a field 'type'."
                     )
                 if exclude_typeless:
-                    warn(
+                    _logger.warning(
                         f"Skipping instance '{entity}' of class '{name}' as the class "
                         f"does not define a field 'type'."
                     )

src/osw/data/import_utility.py

@@ -3,7 +3,6 @@
 import logging
 import re
 import uuid as uuid_module
-import warnings
 from pathlib import Path
 from typing import Any, Callable, Dict, List, Optional, Type, Union
 
@@ -412,9 +411,8 @@ def jsonpath_search_and_return_list(
             # Search in a dramatically reduced number of entries
             result = jp_parse.find(search_tar[str(cls_type)])
         except Exception as e:
-            warnings.warn(
-                f"jsonpath_search_and_return_list() threw and exception:\n{e!s}",
-                stacklevel=2,
+            _logger.warning(
+                f"jsonpath_search_and_return_list() threw and exception:\n{e!s}"
             )
             result = jp_parse.find(search_tar)
     else:
@@ -434,10 +432,9 @@ def jsonpath_search_and_return_list(
                     list_.append(res.value[val_key])
 
     if len(list_) == 0 and warn:
-        warnings.warn(
+        _logger.warning(
             f"jsonpath_search_and_return_list() did not find any "
-            f"results for the jsonpath string '{jp_str}'",
-            stacklevel=3,
+            f"results for the jsonpath string '{jp_str}'"
         )
     return list(set(flatten_list(list_)))
 

src/osw/express.py

@@ -19,7 +19,6 @@
 from pathlib import Path
 from typing import overload
 from uuid import uuid4
-from warnings import warn
 
 import requests
 from opensemantic.v1 import OswBaseModel
@@ -451,7 +450,7 @@ def build_target_fn(
     if mode == FilenameMode.osw_id:
         return osw_id_fn
     if not name:
-        warn(
+        _logger.warning(
             f"No name is stored for '{osw_id_fn}', falling back to the OSW-ID as "
             f"the file name."
         )
@@ -1001,7 +1000,7 @@ def import_with_fallback(
     except Exception as e:
         if dependencies is None:
             dependencies = {}
-            warn(
+            _logger.warning(
                 "No 'dependencies' were passed to the function "
                 "import_with_fallback()! Trying to derive them from 'to_import'."
             )
@@ -1018,7 +1017,7 @@ def import_with_fallback(
                 "No 'dependencies' were passed to the function import_with_fallback() "
                 "and could not be derived from 'to_import'!"
             )
-        warn(
+        _logger.warning(
             f"An exception occurred while loading the module dependencies: \n"
             f'"{e}"\n'
             "A connection to an OSW instance, to fetch the dependencies from, "

src/osw/wiki_tools.py

@@ -1,7 +1,6 @@
 import getpass
 import logging
 import re
-import warnings
 from typing import Dict, List, Optional, Tuple, Union
 
 import mwclient
@@ -327,7 +326,7 @@ def semantic_search_(single_query):
         # count format does, means the result count says nothing about
         # truncation
         if limit and n >= limit:
-            warnings.warn(
+            _logger.warning(
                 f"Query '{single_query}' returned {n} results, which meets the "
                 f"requested limit of {limit}. Results are truncated - raise "
                 f"the limit or page through with '|offset=' to retrieve the "
@@ -348,7 +347,7 @@ def semantic_search_(single_query):
             else:
                 dropped += 1
         if dropped > 0:
-            warnings.warn(
+            _logger.warning(
                 f"Query '{single_query}': {dropped} of {n} results were dropped "
                 f"because the wiki reported them as non-existing pages."
             )

src/osw/wtsite.py

@@ -8,7 +8,6 @@
 import shutil
 import threading
 import urllib
-import warnings
 import xml.etree.ElementTree as et
 from copy import deepcopy
 from datetime import datetime
@@ -17,7 +16,6 @@
 from pprint import pformat
 from time import sleep
 from typing import Any, Dict, List, Optional, Union
-from warnings import warn
 
 import mwclient
 import pyld
@@ -420,10 +418,8 @@ def get_page_(title: str, index: int = None):
                     pages.append(wtpage)
                     if not wtpage.exists:
                         if param.raise_warning:
-                            warnings.warn(
-                                f"WARNING: Page with title '{title}' does not exist.",
-                                RuntimeWarning,
-                                3,
+                            _logger.warning(
+                                f"Page with title '{title}' does not exist."
                             )
                         # throw argument value exception if page does not exist
                         raise ValueError(f"Page with title '{title}' does not exist.")
@@ -833,7 +829,7 @@ def delete_single_page(page_: Union["WtPage", MwPage], comment: str):
                 try:
                     page_ = self._site.pages[page_]
                 except Exception as e:
-                    warn(
+                    _logger.warning(
                         f"Page '{page_}' could not be added to the list of "
                         f"to-be-deleted pages. The following Exception occurred:\n{e}"
                     )
@@ -842,7 +838,7 @@ def delete_single_page(page_: Union["WtPage", MwPage], comment: str):
                     return page_.delete(comment=comment)
                 return page_.delete(reason=comment)
             except Exception as e:
-                warn(
+                _logger.warning(
                     f"Page '{page_}' could not be deleted. "
                     f"The following Exception occurred:\n{e}"
                 )

tests/integration/performance_test.py

@@ -1,3 +1,4 @@
+import logging
 import time
 
 import pytest
@@ -8,7 +9,7 @@
 from osw.wtsite import WtSite
 
 
-def test_fetch_and_load(wiki_domain, wiki_username, wiki_password, mocker):
+def test_fetch_and_load(wiki_domain, wiki_username, wiki_password, mocker, caplog):
     # create a credential file on the default path for osw express
     cm = CredentialManager()  # cred_filepath = Path.cwd() / "accounts.pwd.yaml")
     cm.add_credential(
@@ -74,17 +75,16 @@ def test_fetch_and_load(wiki_domain, wiki_username, wiki_password, mocker):
 
     assert len(result.pages) == 50
 
-    # we should get a warning for the non-existent page
-    # see https://docs.pytest.org/en/stable/how-to/capture-warnings.html
+    # we should get a log warning for the non-existent page
     pages[0] = "IDONOTEXIST"
-    with pytest.warns(RuntimeWarning) as record:
-        result = osw_express.site.get_page(
-            WtSite.GetPageParam(titles=pages[:50], raise_exception=False)
-        )
-        # assert that at least one warning message contains
-        # the missing page title to inform the user
-        assert any("IDONOTEXIST" in str(rec.message) for rec in record)
-        assert len(result.pages) == 50  # assert that the result is still returned
+    caplog.set_level(logging.WARNING, logger="osw")
+    result = osw_express.site.get_page(
+        WtSite.GetPageParam(titles=pages[:50], raise_exception=False)
+    )
+    # assert that at least one warning message contains
+    # the missing page title to inform the user
+    assert any("IDONOTEXIST" in record.message for record in caplog.records)
+    assert len(result.pages) == 50  # assert that the result is still returned
 
     # assert that ValueError is raised when the page does not exist
     pages[0] = "IDONOTEXIST"

tests/integration/test_express_init.py

@@ -781,7 +781,6 @@ def test_none_to_import_raises(self):
         with pytest.raises(ValueError, match="to_import"):
             import_with_fallback(None, {})
 
-    @pytest.mark.filterwarnings("ignore:No 'dependencies' were passed:UserWarning")
     def test_nonexistent_class_no_deps_raises(self):
         """When the class doesn't exist and no dependencies or osw_fpt
         are given, should raise AttributeError."""
@@ -1228,10 +1227,6 @@ def test_live_upload_with_target_fpt(
 class TestLiveImportWithFallback:
     """Test import_with_fallback fallback path with live wiki."""
 
-    @pytest.mark.filterwarnings("ignore:No 'dependencies' were passed:UserWarning")
-    @pytest.mark.filterwarnings(
-        "ignore:An exception occurred while loading the module dependencies:UserWarning"
-    )
     def test_live_fallback_fetches_from_wiki(
         self, wiki_domain, wiki_username, wiki_password
     ):

tests/test_download_filename_modes.py

@@ -4,6 +4,8 @@
 file name, or combine both.
 """
 
+import logging
+
 import pytest
 
 from osw.express import FilenameMode, build_target_fn
@@ -67,9 +69,11 @@ def test_a_directory_in_the_name_is_dropped():
 
 @pytest.mark.parametrize("name", [None, ""])
 @pytest.mark.parametrize("mode", [FilenameMode.name, FilenameMode.name_and_osw_id])
-def test_a_missing_name_falls_back_to_the_osw_id(mode, name):
-    with pytest.warns(UserWarning, match="No name is stored"):
-        assert build_target_fn(mode, OSW_ID_FN, name) == OSW_ID_FN
+def test_a_missing_name_falls_back_to_the_osw_id(mode, name, caplog):
+    caplog.set_level(logging.WARNING, logger="osw")
+    assert build_target_fn(mode, OSW_ID_FN, name) == OSW_ID_FN
+
+    assert any("No name is stored" in record.message for record in caplog.records)
 
 
 def test_an_unknown_mode_is_rejected():