merge remote-tracking branch 'upstream/master' into lazy

.github/workflows/tests.yml

@@ -23,15 +23,21 @@ jobs:
         - '3.12'
         - '3.13'
         - pypy-3.10
+        allow-failure:
+        - false
         include:
         - os: ubuntu-20.04
           python-version: '3.5'
+          allow-failure: false
         - os: ubuntu-20.04
           python-version: '3.6'
+          allow-failure: false
         - os: windows-2022
           python-version: '3.12'
+          allow-failure: false
         - os: macos-13
           python-version: '3.12'
+          allow-failure: false
         - os: ubuntu-22.04
           python-version: 3.14-dev
           allow-failure: true

.pre-commit-config.yaml

@@ -18,14 +18,16 @@ repos:
     args: [--autofix]
   - id: pretty-format-yaml
     args: [--autofix, --indent, '2']
-  - id: pretty-format-toml
-    args: [--autofix]
+- repo: https://github.com/ComPWA/taplo-pre-commit
+  rev: v0.9.3
+  hooks:
+  - id: taplo-format
 - repo: https://github.com/ambv/black
   rev: 24.10.0
   hooks:
   - id: black
 - repo: https://github.com/astral-sh/ruff-pre-commit
-  rev: v0.7.0
+  rev: v0.8.0
   hooks:
   - id: ruff
     args: [--fix, --exit-non-zero-on-fix]

CHANGELOG.rst

@@ -2,7 +2,10 @@
 =============
 
 - Fix possible ``RuntimeError`` when removing all handlers with ``logger.remove()`` due to thread-safety issue (`#1183 <https://github.com/Delgan/loguru/issues/1183>`_, thanks `@jeremyk <https://github.com/jeremyk>`_).
+- Fix ``diagnose=True`` option of exception formatting not working as expected with Python 3.13 (`#1235 <https://github.com/Delgan/loguru/issues/1235>`_, thanks `@etianen <https://github.com/etianen>`_).
 - Fix non-standard level names not fully compatible with ``logging.Formatter()`` (`#1231 <https://github.com/Delgan/loguru/issues/1231>`_, thanks `@yechielb2000 <https://github.com/yechielb2000>`_).
+- Fix inability to display a literal ``"\"`` immediately before color markups (`#988 <https://github.com/Delgan/loguru/issues/988>`_).
+- Fix possible infinite recursion when an exception is raised from a ``__repr__``  method decorated with ``logger.catch()`` (`#1044 <https://github.com/Delgan/loguru/issues/1044>`_).
 - Improve performance of ``datetime`` formatting while logging messages (`#1201 <https://github.com/Delgan/loguru/issues/1201>`_, thanks `@trim21 <https://github.com/trim21>`_).
 - Reduce startup time in the presence of installed but unused ``IPython`` third-party library (`#1001 <https://github.com/Delgan/loguru/issues/1001>`_, thanks `@zakstucke <https://github.com/zakstucke>`_).
 

docs/api/type_hints.rst

@@ -3,7 +3,92 @@
 Type hints
 ==========
 
-.. automodule:: autodoc_stub_file.loguru
+.. |str| replace:: :class:`str`
+.. |namedtuple| replace:: :func:`namedtuple<collections.namedtuple>`
+.. |dict| replace:: :class:`dict`
+
+.. |Logger| replace:: :class:`~loguru._logger.Logger`
+.. |catch| replace:: :meth:`~loguru._logger.Logger.catch()`
+.. |contextualize| replace:: :meth:`~loguru._logger.Logger.contextualize()`
+.. |complete| replace:: :meth:`~loguru._logger.Logger.complete()`
+.. |bind| replace:: :meth:`~loguru._logger.Logger.bind()`
+.. |patch| replace:: :meth:`~loguru._logger.Logger.patch()`
+.. |opt| replace:: :meth:`~loguru._logger.Logger.opt()`
+.. |level| replace:: :meth:`~loguru._logger.Logger.level()`
+
+.. _stub file: https://www.python.org/dev/peps/pep-0484/#stub-files
+.. _string literals: https://www.python.org/dev/peps/pep-0484/#forward-references
+.. _postponed evaluation of annotations: https://www.python.org/dev/peps/pep-0563/
+.. |future| replace:: ``__future__``
+.. _future: https://www.python.org/dev/peps/pep-0563/#enabling-the-future-behavior-in-python-3-7
+.. |loguru-mypy| replace:: ``loguru-mypy``
+.. _loguru-mypy: https://github.com/kornicameister/loguru-mypy
+.. |documentation of loguru-mypy| replace:: documentation of ``loguru-mypy``
+.. _documentation of loguru-mypy:
+    https://github.com/kornicameister/loguru-mypy/blob/master/README.md
+.. _@kornicameister: https://github.com/kornicameister
+
+Loguru relies on a `stub file`_ to document its types. This implies that these types are not
+accessible during execution of your program, however they can be used by type checkers and IDE.
+Also, this means that your Python interpreter has to support `postponed evaluation of annotations`_
+to prevent error at runtime. This is achieved with a |future|_ import in Python 3.7+ or by using
+`string literals`_ for earlier versions.
+
+A basic usage example could look like this:
+
+.. code-block:: python
+
+    from __future__ import annotations
+
+    import loguru
+    from loguru import logger
+
+    def good_sink(message: loguru.Message):
+        print("My name is", message.record["name"])
+
+    def bad_filter(record: loguru.Record):
+        return record["invalid"]
+
+    logger.add(good_sink, filter=bad_filter)
+
+
+.. code-block:: bash
+
+    $ mypy test.py
+    test.py:8: error: TypedDict "Record" has no key 'invalid'
+    Found 1 error in 1 file (checked 1 source file)
+
+There are several internal types to which you can be exposed using Loguru's public API, they are
+listed here and might be useful to type hint your code:
+
+- ``Logger``: the usual |logger| object (also returned by |opt|, |bind| and |patch|).
+- ``Message``: the formatted logging message sent to the sinks (a |str| with ``record``
+  attribute).
+- ``Record``: the |dict| containing all contextual information of the logged message.
+- ``Level``: the |namedtuple| returned by |level| (with ``name``, ``no``, ``color`` and ``icon``
+  attributes).
+- ``Catcher``: the context decorator returned by |catch|.
+- ``Contextualizer``: the context decorator returned by |contextualize|.
+- ``AwaitableCompleter``: the awaitable object returned by |complete|.
+- ``RecordFile``: the ``record["file"]`` with ``name`` and ``path`` attributes.
+- ``RecordLevel``: the ``record["level"]`` with ``name``, ``no`` and ``icon`` attributes.
+- ``RecordThread``: the ``record["thread"]`` with ``id`` and ``name`` attributes.
+- ``RecordProcess``: the ``record["process"]`` with ``id`` and ``name`` attributes.
+- ``RecordException``: the ``record["exception"]`` with ``type``, ``value`` and ``traceback``
+  attributes.
+
+If that is not enough, one can also use the |loguru-mypy|_ library developed by `@kornicameister`_.
+Plugin can be installed separately using::
+
+    pip install loguru-mypy
+
+It helps to catch several possible runtime errors by performing additional checks like:
+
+- ``opt(lazy=True)`` loggers accepting only ``typing.Callable[[], typing.Any]`` arguments
+- ``opt(record=True)`` loggers wrongly calling log handler like so ``logger.info(..., record={})``
+- and even more...
+
+For more details, go to official |documentation of loguru-mypy|_.
 
 
 See also: :ref:`type-hints-source`.

docs/conf.py

@@ -1,22 +1,19 @@
-# -*- coding: utf-8 -*-
-#
-# Configuration file for the Sphinx documentation builder.
-#
-# This file does only contain a selection of the most common options. For a
-# full list see the documentation:
-# http://www.sphinx-doc.org/en/master/config
+"""Configuration file for the Sphinx documentation builder.
+
+This file does only contain a selection of the most common options. For a
+full list see the documentation: http://www.sphinx-doc.org/en/master/config
 
-# -- Path setup --------------------------------------------------------------
+-- Path setup --------------------------------------------------------------
 
-# If extensions (or modules to document with autodoc) are in another directory,
-# add these directories to sys.path here. If the directory is relative to the
-# documentation root, use os.path.abspath to make it absolute, like shown here.
+If extensions (or modules to document with autodoc) are in another directory,
+add these directories to sys.path here. If the directory is relative to the
+documentation root, use os.path.abspath to make it absolute, like shown here.
+"""
 
 import os
 import sys
 
 sys.path.insert(0, os.path.abspath(".."))
-sys.path.insert(0, os.path.abspath("_extensions"))
 
 
 # -- Project information -----------------------------------------------------
@@ -45,7 +42,6 @@
     "sphinx.ext.napoleon",
     "sphinx.ext.viewcode",
     "sphinx.ext.intersphinx",
-    "autodoc_stub_file",
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -176,5 +172,6 @@
 
 
 def setup(app):
+    """Configure the generation of docs."""
     app.add_css_file("css/loguru.css")
     app.add_js_file("js/copybutton.js")