Core: Logging and Exceptional States

[M3ssman]

There's a need for detailed specifications regarding the handling of both Logging and Exception handling.

If OCR-D-Core modules shall be used as library for other client-applications - which I highly approve - the current zoo of logging is very heterogeneous and hard to configure at all (if not impossible). Further, the channels in/from diagnostic information streams is, according to current cli-specs, limited to STDERR . Recent logging may also be broadcasted to other listeners.

Second, invalid states within OCR-D components/classes/functions shall yield a domain specific OCRDException to

• make clear from where exception rises (which is not trivial in client-apps including several libraries)
• respect software development principles like hide internals and prevent tight coupling

[M3ssman]

How to balance between convenient short feedback when ocr-d used as framework and external usage as a library? seems to be the main question.

Other topics:

• How to remove (or at least decrease) settings using global state for logging - initLogging() Ease testing, prevent side-effects
• What needs to be reported with which severity? - Review log level.

Recommendations and Proposals (Python)

• Which log level makes sense in which context?
• Rather use module-level logger.

  "A good convention to use when naming loggers is to use a module-level logger, in each module which uses logging, named as follows:
  logger = logging.getLogger(__name__)
  This means that logger names track the package/module hierarchy, and it’s intuitively obvious where events are logged just from the logger name."

• when used as library, provide NullHandler which swallows by default all log records.

  "It is strongly recommended that you do not add any handlers other than NullHandler to your library’s loggers. This is because the configuration of handlers is the prerogative of the application developer who uses your library." 

  Examples:

  # python snippet
  initLoggin()
  logging.getLogger('ocrd').addHandler(logging.NullHandler())
  logging.getLogger('page-to-alto').addHandler(logging.NullHandler())
  
  # config ini excerpt - must add both logger and handler to overall loggers and handlers sections, too
  [logger_ocrd_processor]
  level=WARN
  handlers=nullHandler
  qualname=processor
  
  [handler_nullHandler]
  class=NullHandler
  args=()
  

• Advanced logging Handlers like SMTP Mail Handler, HTTPHandler