From b6de166f15cd52b9b5d4e454dc12a2a9cfbdbe2f Mon Sep 17 00:00:00 2001 From: Christopher Toth Date: Thu, 29 Oct 2026 12:31:26 -0600 Subject: [PATCH] Document application logging API and exception coverage --- README.rst | 63 ++++++++++++++++++++ agent-notes/improve-logging-documentation.md | 19 ++++++ 2 files changed, 82 insertions(+) create mode 100644 agent-notes/improve-logging-documentation.md diff --git a/README.rst b/README.rst index bf7a150..bbbb5a8 100644 --- a/README.rst +++ b/README.rst @@ -13,3 +13,66 @@ Features * Initialization of debug and error logs * Optionally logs all unhandled tracebacks for later analysis * Support for remote logging to a syslog server + +Usage +----- + +Call setup_logging during application startup on the main thread:: + + import logging + from logger_setup import setup_logging + + setup_logging(error_log="errors.log", debug_log="debug.log") + logger = logging.getLogger(__name__) + logger.info("Application started") + +The function returns Python's root logger and sets its level to DEBUG. +Application and library loggers that propagate to the root use its handlers. +Importing the package does not install handlers or replace sys.excepthook. + +``error_log`` receives WARNING and higher, despite its name. ``debug_log`` +receives DEBUG and higher. Both filenames are optional, open in write mode, +and require existing parent directories. Opening a file replaces previous +contents, even if a later setup step fails; file contents are not rolled back. + +The console handler writes to stderr at INFO by default. Disable it with +``console_level=None``. A packaged application that discards stderr also +discards that console output; configure an error file for retained diagnostics. + +``remote_address=(host, port)`` enables the standard SysLogHandler, with an +ERROR threshold by default. Supply ``application_name`` and +``application_version`` alongside the address. Configuring this handler does +not confirm remote message delivery. + +Exception coverage and lifetime +------------------------------- + +``log_unhandled_exceptions=True`` installs sys.excepthook to log uncaught +main-thread Python exceptions and then call sys.__excepthook__. The delegate +is resolved when the exception occurs. app_framework's later debug bootstrap +uses this to install its debugger delegate. + +With ``error_log`` and ``log_crashes=True``, faulthandler writes fatal traceback +dumps directly to the error-log file descriptor. These are raw dumps without +the normal logging format. This diagnoses crashes; it does not recover from +them. Keep the stream open while faulthandler uses it, and disable or retarget +fault handling before independently closing or replacing the stream. + +The package does not install a thread exception hook or handle every GUI +callback. app_framework logs its executor and wx CallAfter failures separately. +RepeatingTimer also catches and logs callback exceptions. Those mechanisms +are distinct from sys.excepthook and fatal traceback dumps. + +Configure logging before starting worker threads. Explicit process logging +shutdown is available as ``logger_setup.logger_setup.shutdown()``; it invokes +Python's process-wide logging.shutdown, which closes unrelated handlers too. +It is not a private per-package cleanup API. + +Use through app_framework +------------------------- + +app_framework supplies identity and paths under its application data directory, +preserves the preceding error log as ``errors.log.old``, enables debug logging +for source/debug runs, and passes the application's optional remote address. +Those policies belong to the framework; logger_setup does not rotate or retain +logs. The standard application startup path configures logging once. diff --git a/agent-notes/improve-logging-documentation.md b/agent-notes/improve-logging-documentation.md new file mode 100644 index 0000000..dbb7c3d --- /dev/null +++ b/agent-notes/improve-logging-documentation.md @@ -0,0 +1,19 @@ +# Goal + +Document the package's real application use and exception coverage. + +# State + +Documentation-only PR independently based on integrated master. Explain the existing API, thresholds, write mode, fatal dumps, descriptor lifetime, process-wide shutdown, and framework-owned paths and retention. No open PR's commits are inherited. + +# Decisions and why + +Document behavior established by master, rather than promising behavior that exists only in other open PRs. Omit the old stack's claims about UTF-8, transactional construction, repeat replacement and corrected exit cleanup; those are independent proposed fixes. Keep the usage and coverage documentation useful without requiring those PRs. + +# Surprises + +Explicit shutdown is not exported at package level and calls global logging.shutdown. sys.excepthook, executor/wx error handling and fatal dumps cover different paths. + +# Next step + +Read this PR's existing package/README metadata checks. No merge or release.