Add some more documentation and docstrings

guide/config/en/sidebar.yaml

@@ -257,7 +257,7 @@ root:
                   path: /api/sanic.compat.html
                 - label: sanic.helpers
                   path: /api/sanic.helpers.html
-                - label: sanic.log
-                  path: /api/sanic.log.html
+                - label: sanic.logging
+                  path: /api/sanic.logging.html
                 - label: sanic.utils
                   path: /api/sanic.utils.html

guide/content/en/guide/best-practices/logging.md

@@ -191,3 +191,7 @@ Sanic provides additional parameters to the access logger.
 | `status`              | `response`                            | `int`    |
 | `byte`                | `len(response.body)`                  | `int`    |
 | `duration`            | <calculated>                          | `float`  |
+
+## Legacy logging
+
+Many logging changes were introduced in Sanic 24.3. The main changes were related to logging formats. If you prefer the legacy logging format, you can use the `sanic.logging.formatter.LegacyFormatter` and `sanic.logging.formatter.LegacyAccessFormatter` formatters.

sanic/logging/color.py

@@ -19,6 +19,31 @@ class StrEnum(str, Enum):
 
 
 class Colors(StrEnum):  # no cov
+    """
+    Colors for log messages. If the output is not a TTY, the colors will be
+    disabled.
+
+    Can be used like this:
+
+    .. code-block:: python
+
+        from sanic.log import logger, Colors
+
+        logger.info(f"{Colors.GREEN}This is a green message{Colors.END}")
+
+
+    Attributes:
+        END: Reset the color
+        BOLD: Bold text
+        BLUE: Blue text
+        GREEN: Green text
+        PURPLE: Purple text
+        RED: Red text
+        SANIC: Sanic pink
+        YELLOW: Yellow text
+        GREY: Grey text
+    """
+
     END = "\033[0m" if is_atty() else ""
     BOLD = "\033[1m" if is_atty() else ""
     BLUE = "\033[34m" if is_atty() else ""

sanic/logging/deprecation.py

@@ -11,17 +11,19 @@ def deprecation(message: str, version: float):  # no cov
     Example when a feature is being removed. In this case, version
     should be AT LEAST next version + 2
 
+    .. code-block:: python
+
         deprecation("Helpful message", 99.9)
 
     Example when a feature is deprecated but not being removed:
 
+    .. code-block:: python
+
         deprecation("Helpful message", 0)
 
-    :param message: The message of the notice
-    :type message: str
-    :param version: The version when the feature will be removed. If it is
-      not being removed, then set version=0.
-    :type version: float
+    Args:
+        message (str): Deprecation message
+        version (float): Version when the feature will be removed
     """
     version_display = f" v{version}" if version else ""
     version_info = f"[DEPRECATION{version_display}] "

sanic/logging/filter.py

@@ -2,6 +2,10 @@
 
 
 class VerbosityFilter(logging.Filter):
+    """
+    Filter log records based on verbosity level.
+    """
+
     verbosity: int = 0
 
     def filter(self, record: logging.LogRecord) -> bool:

sanic/logging/formatter.py

@@ -15,6 +15,14 @@
 
 
 class AutoFormatter(logging.Formatter):
+    """
+    Automatically sets up the formatter based on the environment.
+
+    It will switch between the Debug and Production formatters based upon
+    how the environment is set up. Additionally, it will automatically
+    detect if the output is a TTY and colorize the output accordingly.
+    """
+
     SETUP = False
     ATTY = is_atty()
     IDENT = os.environ.get("SANIC_WORKER_IDENTIFIER", "Main ")
@@ -59,6 +67,13 @@ def _make_format(self) -> str:
 
 
 class DebugFormatter(AutoFormatter):
+    """
+    The DebugFormatter is used for development and debugging purposes.
+
+    It can be used directly, or it will be automatically selected if the
+    environment is set up for development and is using the AutoFormatter.
+    """
+
     IDENT_LIMIT = 5
     MESSAGE_START = 13
 
@@ -69,6 +84,13 @@ def _set_levelname(self, record: logging.LogRecord) -> None:
 
 
 class ProdFormatter(AutoFormatter):
+    """
+    The ProdFormatter is used for production environments.
+
+    It can be used directly, or it will be automatically selected if the
+    environment is set up for production and is using the AutoFormatter.
+    """
+
     IDENT_LIMIT = 5
     MESSAGE_START = 42
     PREFIX_FORMAT = (
@@ -78,6 +100,26 @@ class ProdFormatter(AutoFormatter):
 
 
 class LegacyFormatter(AutoFormatter):
+    """
+    The LegacyFormatter is used if you want to use the old style of logging.
+
+    You can use it as follows, typically in conjunction with the
+    LegacyAccessFormatter:
+
+    .. code-block:: python
+
+        from sanic.log import LOGGING_CONFIG_DEFAULTS
+
+        LOGGING_CONFIG_DEFAULTS["formatters"] = {
+            "generic": {
+                "class": "sanic.logging.formatter.LegacyFormatter"
+            },
+            "access": {
+                "class": "sanic.logging.formatter.LegacyAccessFormatter"
+            },
+        }
+    """
+
     PREFIX_FORMAT = "%(asctime)s [%(process)s] [%(levelname)s] "
     DATE_FORMAT = "[%Y-%m-%d %H:%M:%S %z]"
 
@@ -106,6 +148,26 @@ def _set_levelname(self, record: logging.LogRecord) -> None:
 
 
 class LegacyAccessFormatter(AutoAccessFormatter):
+    """
+    The LegacyFormatter is used if you want to use the old style of logging.
+
+    You can use it as follows, typically in conjunction with the
+    LegacyFormatter:
+
+    .. code-block:: python
+
+        from sanic.log import LOGGING_CONFIG_DEFAULTS
+
+        LOGGING_CONFIG_DEFAULTS["formatters"] = {
+            "generic": {
+                "class": "sanic.logging.formatter.LegacyFormatter"
+            },
+            "access": {
+                "class": "sanic.logging.formatter.LegacyAccessFormatter"
+            },
+        }
+    """
+
     PREFIX_FORMAT = "%(asctime)s - (%(name)s)[%(levelname)s][%(host)s]: "
     MESSAGE_FORMAT = "%(request)s %(message)s %(status)s %(byte)s"