refactor: Prepare loggers for simplification

Before this commit we supported having multiple loggers. After this commit we only use one single, global logger, with the name `"griffe"`. It allows us to simplify a few other things related to logging.

To keep this backward compatible before v1, we mainly used Yore comments.

Author: pawamoy

config/pytest.ini

@@ -13,3 +13,7 @@ filterwarnings =
   # TODO: remove once pytest-xdist 4 is released
   ignore:.*rsyncdir:DeprecationWarning:xdist
   ignore:.*slated for removal in Python:DeprecationWarning:.*
+  # YORE: Bump 1.0.0: Remove line.
+  ignore:.*`get_logger`:DeprecationWarning:_griffe
+  # YORE: Bump 1.0.0: Remove line.
+  ignore:.*`name`:DeprecationWarning:_griffe

docs/reference/api/loggers.md

@@ -3,11 +3,22 @@
 ## **Main API**
 
 ::: griffe.DEFAULT_LOG_LEVEL
+    options:
+        annotations_path: full
 
-::: griffe.get_logger
+<!-- YORE: Bump 1.0.0: Uncomment line. -->
+<!-- ::: griffe.logger -->
+
+::: griffe.Logger
 
 ::: griffe.LogLevel
 
 ## **Advanced API**
 
+::: griffe.patch_logger
+
+## **Deprecated API**
+
+::: griffe.get_logger
+
 ::: griffe.patch_loggers

src/_griffe/agents/inspector.py

@@ -34,6 +34,9 @@
 from _griffe.expressions import safe_get_annotation
 from _griffe.extensions.base import Extensions, load_extensions
 from _griffe.importer import dynamic_import
+
+# YORE: Bump 1.0.0: Replace `_logger` with `logger` within file.
+# YORE: Bump 1.0.0: Replace `get_logger` with `logger` within line.
 from _griffe.logger import get_logger
 from _griffe.models import Alias, Attribute, Class, Docstring, Function, Module, Parameter, Parameters
 
@@ -44,7 +47,7 @@
     from _griffe.expressions import Expr
 
 
-# YORE: Bump 1.0.0: Regex-replace `\.[^"]+` with `` within line.
+# YORE: Bump 1.0.0: Remove line.
 _logger = get_logger("griffe.agents.inspector")
 _empty = Signature.empty
 

src/_griffe/agents/nodes/assignments.py

@@ -5,11 +5,6 @@
 import ast
 from typing import Any, Callable
 
-from _griffe.logger import get_logger
-
-# YORE: Bump 1.0.0: Regex-replace `\.[^"]+` with `` within line.
-_logger = get_logger("griffe.agents.nodes._names")
-
 
 def _get_attribute_name(node: ast.Attribute) -> str:
     return f"{get_name(node.value)}.{node.attr}"

src/_griffe/agents/nodes/ast.py

@@ -6,10 +6,6 @@
 from typing import Iterator
 
 from _griffe.exceptions import LastNodeError
-from _griffe.logger import get_logger
-
-# YORE: Bump 1.0.0: Regex-replace `\.[^"]+` with `` within line.
-_logger = get_logger("griffe.agents.nodes._ast")
 
 
 def ast_kind(node: AST) -> str:

src/_griffe/agents/nodes/docstrings.py

@@ -4,9 +4,11 @@
 
 import ast
 
+# YORE: Bump 1.0.0: Replace `_logger` with `logger` within file.
+# YORE: Bump 1.0.0: Replace `get_logger` with `logger` within line.
 from _griffe.logger import get_logger
 
-# YORE: Bump 1.0.0: Regex-replace `\.[^"]+` with `` within line.
+# YORE: Bump 1.0.0: Remove line.
 _logger = get_logger("griffe.agents.nodes._docstrings")
 
 

src/_griffe/agents/nodes/exports.py

@@ -9,13 +9,16 @@
 
 from _griffe.agents.nodes.values import get_value
 from _griffe.enumerations import LogLevel
+
+# YORE: Bump 1.0.0: Replace `_logger` with `logger` within file.
+# YORE: Bump 1.0.0: Replace `get_logger` with `logger` within line.
 from _griffe.logger import get_logger
 
 if TYPE_CHECKING:
     from _griffe.models import Module
 
 
-# YORE: Bump 1.0.0: Regex-replace `\.[^"]+` with `` within line.
+# YORE: Bump 1.0.0: Remove line.
 _logger = get_logger("griffe.agents.nodes._all")
 
 

src/_griffe/agents/nodes/imports.py

@@ -4,18 +4,12 @@
 
 from typing import TYPE_CHECKING
 
-from _griffe.logger import get_logger
-
 if TYPE_CHECKING:
     import ast
 
     from _griffe.models import Module
 
 
-# YORE: Bump 1.0.0: Regex-replace `\.[^"]+` with `` within line.
-_logger = get_logger("griffe.agents.nodes._imports")
-
-
 def relative_to_absolute(node: ast.ImportFrom, name: ast.alias, current_module: Module) -> str:
     """Convert a relative import path to an absolute one.
 

src/_griffe/agents/nodes/parameters.py

@@ -7,10 +7,6 @@
 from typing import Iterable, List, Optional, Tuple, Union
 
 from _griffe.enumerations import ParameterKind
-from _griffe.logger import get_logger
-
-# YORE: Bump 1.0.0: Regex-replace `\.[^"]+` with `` within line.
-_logger = get_logger("griffe.agents.nodes._parameters")
 
 ParametersType = List[Tuple[str, Optional[ast.AST], ParameterKind, Optional[Union[str, ast.AST]]]]
 """Type alias for the list of parameters of a function."""

src/_griffe/agents/nodes/runtime.py

@@ -8,9 +8,12 @@
 from typing import Any, ClassVar, Sequence
 
 from _griffe.enumerations import ObjectKind
+
+# YORE: Bump 1.0.0: Replace `_logger` with `logger` within file.
+# YORE: Bump 1.0.0: Replace `get_logger` with `logger` within line.
 from _griffe.logger import get_logger
 
-# YORE: Bump 1.0.0: Regex-replace `\.[^"]+` with `` within line.
+# YORE: Bump 1.0.0: Remove line.
 _logger = get_logger("griffe.agents.nodes._runtime")
 
 _builtin_module_names = {_.lstrip("_") for _ in sys.builtin_module_names}

src/_griffe/agents/nodes/values.py

@@ -6,6 +6,8 @@
 import sys
 from typing import TYPE_CHECKING
 
+# YORE: Bump 1.0.0: Replace `_logger` with `logger` within file.
+# YORE: Bump 1.0.0: Replace `get_logger` with `logger` within line.
 from _griffe.logger import get_logger
 
 # YORE: EOL 3.8: Replace block with line 4.
@@ -17,7 +19,7 @@
 if TYPE_CHECKING:
     from pathlib import Path
 
-# YORE: Bump 1.0.0: Regex-replace `\.[^"]+` with `` within line.
+# YORE: Bump 1.0.0: Remove line.
 _logger = get_logger("griffe.agents.nodes._values")
 
 

src/_griffe/cli.py

@@ -32,6 +32,9 @@
 from _griffe.extensions.base import load_extensions
 from _griffe.git import get_latest_tag, get_repo_root
 from _griffe.loader import GriffeLoader, load, load_git
+
+# YORE: Bump 1.0.0: Replace `_logger` with `logger` within file.
+# YORE: Bump 1.0.0: Replace `get_logger` with `logger` within line.
 from _griffe.logger import get_logger
 
 if TYPE_CHECKING:
@@ -40,7 +43,7 @@
 
 DEFAULT_LOG_LEVEL = os.getenv("GRIFFE_LOG_LEVEL", "INFO").upper()
 
-# YORE: Bump 1.0.0: Regex-replace `\.[^"]+` with `` within line.
+# YORE: Bump 1.0.0: Remove line.
 _logger = get_logger("griffe.cli")
 
 

src/_griffe/diff.py

@@ -12,6 +12,9 @@
 from _griffe.enumerations import BreakageKind, ExplanationStyle, ParameterKind
 from _griffe.exceptions import AliasResolutionError
 from _griffe.git import _WORKTREE_PREFIX
+
+# YORE: Bump 1.0.0: Replace `_logger` with `logger` within file.
+# YORE: Bump 1.0.0: Replace `get_logger` with `logger` within line.
 from _griffe.logger import get_logger
 
 if TYPE_CHECKING:
@@ -22,7 +25,7 @@
 _POSITIONAL_KEYWORD_ONLY = frozenset((ParameterKind.positional_only, ParameterKind.keyword_only))
 _VARIADIC = frozenset((ParameterKind.var_positional, ParameterKind.var_keyword))
 
-# YORE: Bump 1.0.0: Regex-replace `\.[^"]+` with `` within line.
+# YORE: Bump 1.0.0: Remove line.
 _logger = get_logger("griffe.diff")
 
 

src/_griffe/docstrings/google.py

@@ -44,7 +44,8 @@
     from _griffe.expressions import Expr
     from _griffe.models import Docstring
 
-# YORE: Bump 1.0.0: Regex-replace `\.[^"]+` with `` within line.
+# YORE: Bump 1.0.0: Regex-replace `\b_warn\b` with `docstring_warning` within file.
+# YORE: Bump 1.0.0: Remove line.
 _warn = docstring_warning("griffe.docstrings.google")
 
 _section_kind = {

src/_griffe/docstrings/numpy.py

@@ -63,7 +63,8 @@
     from _griffe.models import Docstring
 
 
-# YORE: Bump 1.0.0: Regex-replace `\.[^"]+` with `` within line.
+# YORE: Bump 1.0.0: Regex-replace `\b_warn\b` with `docstring_warning` within file.
+# YORE: Bump 1.0.0: Remove line.
 _warn = docstring_warning("griffe.docstrings.numpy")
 
 _section_kind = {

src/_griffe/docstrings/sphinx.py

@@ -29,7 +29,8 @@
     from _griffe.expressions import Expr
     from _griffe.models import Docstring
 
-# YORE: Bump 1.0.0: Regex-replace `\.[^"]+` with `` within line.
+# YORE: Bump 1.0.0: Regex-replace `\b_warn\b` with `docstring_warning` within file.
+# YORE: Bump 1.0.0: Remove line.
 _warn = docstring_warning("griffe.docstrings.sphinx")
 
 # TODO: Examples: from the documentation, we're not sure there is a standard format for examples

src/_griffe/docstrings/utils.py

@@ -2,20 +2,24 @@
 
 from __future__ import annotations
 
+import warnings
 from ast import PyCF_ONLY_AST
 from contextlib import suppress
-from typing import TYPE_CHECKING, Protocol
+from typing import TYPE_CHECKING, Protocol, overload
 
 from _griffe.enumerations import LogLevel
 from _griffe.exceptions import BuiltinModuleError
 from _griffe.expressions import safe_get_annotation
+
+# YORE: Bump 1.0.0: Replace `get_logger` with `logger` within line.
 from _griffe.logger import get_logger
 
 if TYPE_CHECKING:
     from _griffe.expressions import Expr
     from _griffe.models import Docstring
 
 
+# YORE: Bump 1.0.0: Remove block.
 class DocstringWarningCallable(Protocol):
     """A callable that logs a warning message."""
 
@@ -30,23 +34,58 @@ def __call__(self, docstring: Docstring, offset: int, message: str, log_level: L
         """
 
 
-def docstring_warning(name: str) -> DocstringWarningCallable:
-    """Create and return a warn function.
+# YORE: Bump 1.0.0: Remove line.
+_sentinel = object()
 
-    Parameters:
-        name: The logger name.
 
-    Returns:
-        A function used to log parsing warnings.
+# YORE: Bump 1.0.0: Remove block.
+@overload
+def docstring_warning(name: str) -> DocstringWarningCallable: ...
+
+
+# YORE: Bump 1.0.0: Remove block.
+@overload
+def docstring_warning(
+    docstring: Docstring,
+    offset: int,
+    message: str,
+    log_level: LogLevel = LogLevel.warning,
+) -> None: ...
+
+
+def docstring_warning(  # type: ignore[misc]
+    # YORE: Bump 1.0.0: Remove line.
+    name: str | None = None,
+    # YORE: Bump 1.0.0: Replace line with `docstring: Docstring,`.
+    docstring: Docstring = _sentinel,  # type: ignore[assignment]
+    # YORE: Bump 1.0.0: Replace line with `offset: int,`.
+    offset: int = _sentinel,  # type: ignore[assignment]
+    # YORE: Bump 1.0.0: Replace line with `message: str,`.
+    message: str = _sentinel,  # type: ignore[assignment]
+    log_level: LogLevel = LogLevel.warning,
+    # YORE: Bump 1.0.0: Replace line with `) -> None:`.
+) -> DocstringWarningCallable | None:
+    """Log a warning when parsing a docstring.
 
     This function logs a warning message by prefixing it with the filepath and line number.
 
-    Other parameters: Parameters of the returned function:
-        docstring (Docstring): The docstring object.
-        offset (int): The offset in the docstring lines.
-        message (str): The message to log.
+    Parameters:
+        name: Deprecated. If passed, the function returns a callable, and other arguments are ignored.
+        docstring: The docstring object.
+        offset: The offset in the docstring lines.
+        message: The message to log.
+
+    Returns:
+        A function used to log parsing warnings if `name` was passed, else none.
     """
-    logger = get_logger(name)
+    # YORE: Bump 1.0.0: Remove block.
+    if name is not None:
+        warnings.warn("The `name` parameter is deprecated.", DeprecationWarning, stacklevel=1)
+        logger = get_logger(name)
+    else:
+        if docstring is _sentinel or offset is _sentinel or message is _sentinel:
+            raise ValueError("Missing required arguments docstring/offset/message.")
+        logger = get_logger("griffe")
 
     def warn(docstring: Docstring, offset: int, message: str, log_level: LogLevel = LogLevel.warning) -> None:
         try:
@@ -58,7 +97,11 @@ def warn(docstring: Docstring, offset: int, message: str, log_level: LogLevel =
         log = getattr(logger, log_level.value)
         log(f"{prefix}:{(docstring.lineno or 0)+offset}: {message}")
 
-    return warn
+    if name is not None:
+        return warn
+
+    warn(docstring, offset, message, log_level)
+    return None
 
 
 def parse_docstring_annotation(

src/_griffe/expressions.py

@@ -13,6 +13,9 @@
 from _griffe.agents.nodes.parameters import get_parameters
 from _griffe.enumerations import LogLevel, ParameterKind
 from _griffe.exceptions import NameResolutionError
+
+# YORE: Bump 1.0.0: Replace `_logger` with `logger` within file.
+# YORE: Bump 1.0.0: Replace `get_logger` with `logger` within line.
 from _griffe.logger import get_logger
 
 if TYPE_CHECKING:
@@ -21,7 +24,7 @@
     from _griffe.models import Class, Module
 
 
-# YORE: Bump 1.0.0: Regex-replace `\.[^"]+` with `` within line.
+# YORE: Bump 1.0.0: Remove line.
 _logger = get_logger("griffe.expressions")
 
 

src/_griffe/finder.py

@@ -25,14 +25,17 @@
 from typing import TYPE_CHECKING, ClassVar, Iterator, Sequence, Tuple
 
 from _griffe.exceptions import UnhandledEditableModuleError
+
+# YORE: Bump 1.0.0: Replace `_logger` with `logger` within file.
+# YORE: Bump 1.0.0: Replace `get_logger` with `logger` within line.
 from _griffe.logger import get_logger
 
 if TYPE_CHECKING:
     from typing import Pattern
 
     from _griffe.models import Module
 
-# YORE: Bump 1.0.0: Regex-replace `\.[^"]+` with `` within line.
+# YORE: Bump 1.0.0: Remove line.
 _logger = get_logger("griffe.finder")
 
 _editable_editables_patterns = [re.compile(pat) for pat in (r"^__editables_\w+\.py$", r"^_editable_impl_\w+\.py$")]