Add logging-based error reporting

docs/command_line.md

@@ -37,25 +37,30 @@ Usage: docstub run [OPTIONS] PACKAGE_PATH
   annotations or to override them.
 
 Options:
-  -o, --out-dir PATH  Set output directory explicitly. Stubs will be directly
-                      written into that directory while preserving the
-                      directory structure under `PACKAGE_PATH`. Otherwise,
-                      stubs are generated inplace.
-  --config PATH       Set one or more configuration file(s) explicitly.
-                      Otherwise, it will look for a `pyproject.toml` or
-                      `docstub.toml` in the current directory.
-  --ignore GLOB       Ignore files matching this glob-style pattern. Can be
-                      used multiple times.
-  --group-errors      Group identical errors together and list where they
-                      occurred. Will delay showing errors until all files have
-                      been processed. Otherwise, simply report errors as the
-                      occur.
-  --allow-errors INT  Allow this many or fewer errors. If docstub reports
-                      more, exit with error code '1'. This is useful to adopt
-                      docstub gradually.  [default: 0; x>=0]
-  --no-cache          Ignore pre-existing cache and don't create a new one.
-  -v, --verbose       Print more details (repeatable).
-  -h, --help          Show this message and exit.
+  -o, --out-dir PATH     Set output directory explicitly. Stubs will be
+                         directly written into that directory while preserving
+                         the directory structure under `PACKAGE_PATH`.
+                         Otherwise, stubs are generated inplace.
+  --config PATH          Set one or more configuration file(s) explicitly.
+                         Otherwise, it will look for a `pyproject.toml` or
+                         `docstub.toml` in the current directory.
+  --ignore GLOB          Ignore files matching this glob-style pattern. Can be
+                         used multiple times.
+  --group-errors         Group identical errors together and list where they
+                         occurred. Will delay showing errors until all files
+                         have been processed. Otherwise, simply report errors
+                         as the occur.
+  --allow-errors INT     Allow this many or fewer errors. If docstub reports
+                         more, exit with error code '1'. This is useful to
+                         adopt docstub gradually.   [default: 0; x>=0]
+  -W, --fail-on-warning  Return non-zero exit code when a warning is raised.
+                         Will add to '--allow-errors'.
+  --no-cache             Ignore pre-existing cache and don't create a new one.
+  -v, --verbose          Print more details. Use once to show information
+                         messages. Use '-vv' to print debug messages.
+  -q, --quiet            Print less details. Use once to hide warnings. Use
+                         '-qq' to completely silence output.
+  -h, --help             Show this message and exit.
 ```
 
 <!--- end cli-docstub-run --->
@@ -75,7 +80,10 @@ Usage: docstub clean [OPTIONS]
   one exists, remove it.
 
 Options:
-  -v, --verbose  Print more details (repeatable).
+  -v, --verbose  Print more details. Use once to show information messages.
+                 Use '-vv' to print debug messages.
+  -q, --quiet    Print less details. Use once to hide warnings. Use '-qq' to
+                 completely silence output.
   -h, --help     Show this message and exit.
 ```
 

src/docstub/_analysis.py

@@ -14,7 +14,7 @@
 
 from ._utils import accumulate_qualname, module_name_from_path, pyfile_checksum
 
-logger = logging.getLogger(__name__)
+logger: logging.Logger = logging.getLogger(__name__)
 
 
 def _shared_leading_qualname(*qualnames):
@@ -104,6 +104,18 @@ def typeshed_Incomplete(cls):
         return import_
 
     def format_import(self, relative_to=None):
+        """Format import as valid Python import statement.
+
+        Parameters
+        ----------
+        relative_to : str, optional
+            If a dot-delimited module name is given, format the import relative
+            to it.
+
+        Returns
+        -------
+        formatted : str
+        """
         if self.implicit:
             msg = f"cannot import implicit object: {self.implicit!r}"
             raise RuntimeError(msg)
@@ -265,20 +277,6 @@ def common_known_types():
     return types
 
 
-@dataclass(slots=True, kw_only=True)
-class TypeCollectionResult:
-    types: dict[str, PyImport]
-    type_prefixes: dict[str, PyImport]
-
-    @classmethod
-    def serialize(cls, result):
-        pass
-
-    @classmethod
-    def deserialize(cls, result):
-        pass
-
-
 class TypeCollector(cst.CSTVisitor):
     """Collect types from a given Python file.
 
@@ -296,7 +294,13 @@ class TypeCollector(cst.CSTVisitor):
     """
 
     class ImportSerializer:
-        """Implements the `FuncSerializer` protocol to cache `TypeCollector.collect`."""
+        """Implements the `FuncSerializer` protocol to cache `TypeCollector.collect`.
+
+        Attributes
+        ----------
+        suffix : ClassVar[str]
+        encoding : ClassVar[str]
+        """
 
         suffix = ".json"
         encoding = "utf-8"
@@ -524,7 +528,7 @@ def _resolve_nickname(self, name):
             resolved = name
         else:
             logger.warning(
-                "reached limit while resolving nicknames for %r in %s, using %r",
+                "Reached limit while resolving nicknames for %r in %s, using %r",
                 original,
                 self.current_file or "<file not known>",
                 resolved,
@@ -572,7 +576,7 @@ def match(self, search):
                     "%r (original %r) in %s matches multiple types %r, using %r",
                     search,
                     original_search,
-                    self.current_file or "<file not known>",
+                    self.current_file or "<file?>",
                     matches.keys(),
                     shortest_key,
                 )

src/docstub/_cache.py

@@ -2,21 +2,21 @@
 from functools import cached_property
 from typing import Any, Protocol
 
-logger = logging.getLogger(__name__)
+logger: logging.Logger = logging.getLogger(__name__)
 
 
-CACHE_DIR_NAME = ".docstub_cache"
+CACHE_DIR_NAME: str = ".docstub_cache"
 
 
-CACHEDIR_TAG_CONTENT = """\
+CACHEDIR_TAG_CONTENT: str = """\
 Signature: 8a477f597d28d172789f06886806bc55
 # Mark this directory as a cache [1], created by docstub [2]
 # [1] https://bford.info/cachedir/
 # [2] https://github.com/scientific-python/docstub
 """
 
 
-GITHUB_IGNORE_CONTENT = """\
+GITHUB_IGNORE_CONTENT: str = """\
 # Make git ignore this cache directory, created by docstub [1]
 # [1] https://github.com/scientific-python/docstub
 *
@@ -172,7 +172,7 @@ def cache_dir(self):
         create_cache(self._cache_dir)
 
         if _directory_size(self._cache_dir) > 512 * 1024**2:
-            logger.warning("cache size at %r exceeds 512 MiB", self._cache_dir)
+            logger.warning("Cache size at %r exceeds 512 MiB", self._cache_dir)
 
         return self._cache_dir