feat: add custom logging with TRACE support for API classes

Adds _ensure_logger() to API module with TRACE-aware format selection
and improves HTTP error handling with reason propagation.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: joamag

CHANGELOG.md

@@ -9,7 +9,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
-*
+* TRACE-aware logging format in API module's `_ensure_logger()`
+* Custom logging support for API classes with configurable level and format
 
 ### Changed
 

src/appier/api.py

@@ -45,13 +45,19 @@
 import hashlib
 import logging
 
+from . import log
 from . import base
 from . import http
+from . import config
 from . import legacy
 from . import observer
 from . import exceptions
 from . import structures
 
+_LOGGERS = {}
+""" Dictionary of loggers that have already been initialized,
+used to ensure singleton-based initialization of named loggers """
+
 
 class API(observer.Observable):
     """
@@ -319,9 +325,53 @@ def handle_error(self, error):
     def logger(self):
         if self.owner:
             return self.owner.logger
+        elif hasattr(self, "_log_name") and self._log_name:
+            return self._ensure_logger(self._log_name)
         else:
             return logging.getLogger()
 
+    @classmethod
+    def _ensure_logger(cls, name):
+        # verifies if the logger already exists in the global
+        # loggers map and returns it immediately if so
+        if name in _LOGGERS:
+            return _LOGGERS[name]
+
+        # retrieves the logging level and format from the
+        # current configuration defaulting to sane values
+        level_s = config.conf("LEVEL", None)
+        format = config.conf("LOGGING_FORMAT", None)
+
+        # resolves the logging level using the application's
+        # level method falling back to the INFO level
+        level = base.APP._level(level_s) if base.APP else None
+        level = level or logging.INFO
+
+        # resolves the logging format taking into account if
+        # the level is TRACE to use the verbose format
+        is_trace = level <= log.TRACE
+        format = format or (
+            log.LOGGING_FORMAT_TRACE if is_trace else log.LOGGING_FORMAT
+        )
+
+        # creates the logger with the provided name and sets
+        # the resolved logging level in it
+        logger = logging.getLogger(name)
+        logger.setLevel(level)
+
+        # creates the stream handler setting the level and the
+        # formatter using the thread aware formatter
+        handler = logging.StreamHandler()
+        handler.setLevel(level)
+        handler.setFormatter(log.ThreadFormatter(format))
+
+        # adds the handler to the logger and stores it in the
+        # global loggers map for later retrieval
+        logger.addHandler(handler)
+
+        _LOGGERS[name] = logger
+        return logger
+
 
 class OAuthAPI(API):
     """

src/appier/http.py

@@ -278,7 +278,8 @@ def _method(method, *args, **kwargs):
             result = method(*args, **kwargs)
         except legacy.HTTPError as error:
             code = error.getcode()
-            raise exceptions.HTTPError(error, code)
+            reason = error.reason if hasattr(error, "reason") else None
+            raise exceptions.HTTPError(error, code=code, message=reason)
 
     return result
 
@@ -875,7 +876,13 @@ def _resolve_netius(url, method, headers, data, silent, timeout, **kwargs):
     code = response.getcode()
     is_error = _is_error(code)
     if is_error:
-        raise legacy.HTTPError(url, code, "HTTP retrieval problem", None, response)
+        raise legacy.HTTPError(
+            url,
+            code,
+            "HTTP retrieval problem: %s" % error if error else "HTTP retrieval problem",
+            None,
+            response,
+        )
 
     # returns the final response object to the upper layers, this object
     # may be used freely under the compatibility interface it provides