o u] @sdZddlZddlZddlZddlZejjddddddZ e e \Z Z Z ZZZe j ej d e j ej e j ej e jej d e jeje jejiZeee deeeded Zeee ejd d d ZeZGdddejZejs~eeddZddZ ddZ!ddZ"ddZ#ddZ$ddZ%ddZ&d d!Z'd"d#Z(d$d%Z)d&d'Z*Gd(d)d)ejZ+Gd*d+d+ejZ,d,d-Z-dS).aa Functions to aid library logging. The default logging :data:`~stem.util.log.Runlevel` is usually NOTICE and above. **Stem users are more than welcome to listen for stem events, but these functions are not being vended to our users. They may change in the future, use them at your own risk.** **Module Overview:** :: get_logger - provides the stem's Logger instance logging_level - converts a runlevel to its logging number escape - escapes special characters in a message in preparation for logging log - logs a message at the given runlevel log_once - logs a message, deduplicating if it has already been logged trace - logs a message at the TRACE runlevel debug - logs a message at the DEBUG runlevel info - logs a message at the INFO runlevel notice - logs a message at the NOTICE runlevel warn - logs a message at the WARN runlevel error - logs a message at the ERROR runlevel LogBuffer - Buffers logged events so they can be iterated over. |- is_empty - checks if there's events in our buffer +- __iter__ - iterates over and removes the buffered events log_to_stdout - reports further logged events to stdout .. data:: Runlevel (enum) Enumeration for logging runlevels. ========== =========== Runlevel Description ========== =========== **ERROR** critical issue occurred, the user needs to be notified **WARN** non-critical issue occurred that the user should be aware of **NOTICE** information that is helpful to the user **INFO** high level library activity **DEBUG** low level library activity **TRACE** request/reply logging ========== =========== NTRACEDEBUGINFONOTICEWARNERRORstem'%(asctime)s [%(levelname)s] %(message)s%m/%d/%Y %H:%M:%SZfmtZdatefmtc@eZdZddZddZdS) _NullHandlercCstjj|tjdddS)Nrlevel)loggingHandler__init__FATALselfr//usr/lib/python3/dist-packages/stem/util/log.pyr`sz_NullHandler.__init__cCsdSNrrrecordrrremitcsz_NullHandler.emitN__name__ __module__ __qualname__rrrrrrr_s rcCstS)zH Provides the stem logger. :returns: **logging.Logger** for stem )LOGGERrrrr get_loggerksr"cCs|rt|StjdS)z Translates a runlevel into the value expected by the logging module. :param stem.util.log.Runlevel runlevel: runlevel to be returned, no logging if **None** r) LOG_VALUESrrrunlevelrrr logging_levelus r&cCs&tjD] }|jttkrdSqdS)z Checks if we're logging at the trace runlevel. .. versionadded:: 1.6.0 :returns: **True** if we're logging at the trace runlevel and **False** otherwise TF)r"handlersrr&r)Zhandlerrrr is_tracings r(cCs6tjr tjj|}dD] \}}|||}q|S)z Escapes specific sequences for logging (newlines, tabs, carriage returns). If the input is **bytes** then this converts it to **unicode** under python 3.x. :param str message: string to be escaped :returns: str that is escaped )) z\n) z\r) z\t)r ZprereqZ is_python_3utilZ str_toolsZ _to_unicodereplace)messagepatternZ replacementrrrescapes  r0cCs|r tt||dSdS)z Logs a message at the given runlevel. :param stem.util.log.Runlevel runlevel: runlevel to log the message at, logging is skipped if **None** :param str message: message to be logged N)r!logr#)r%r.rrrr1sr1cCs(|r|tvrdSt|t||dS)a Logs a message at the given runlevel. If a message with this ID has already been logged then this is a no-op. :param str message_id: unique message identifier to deduplicate on :param stem.util.log.Runlevel runlevel: runlevel to log the message at, logging is skipped if **None** :param str message: message to be logged :returns: **True** if we log the message, **False** otherwise FN)DEDUPLICATION_MESSAGE_IDSaddr1)Z message_idr%r.rrrlog_onces  r4cCttj|dSr)r1Runlevelrr.rrrtracer8cCr5r)r1r6rr7rrrdebugr9r:cCr5r)r1r6rr7rrrinfor9r;cCr5r)r1r6rr7rrrnoticer9r<cCr5r)r1r6rr7rrrwarnr9r=cCr5r)r1r6rr7rrrerrorr9r>c@s2eZdZdZd ddZddZddZd d Zd S) LogBuffera> Basic log handler that listens for stem events and stores them so they can be read later. Log entries are cleared as they are read. .. versionchanged:: 1.4.0 Added the yield_records argument. .. deprecated:: 1.8.0 This will be dropped in Stem 2.x. Use python's logging.BufferingHandler instead. FcCs*tjj|t|dt|_g|_||_dS)Nr)rrrr& FORMATTER formatter_buffer_yield_records)rr%Z yield_recordsrrrrs zLogBuffer.__init__cCs t|j Sr)boolrBrrrris_emptys zLogBuffer.is_emptyccs:|jr|jd}|jr|n|j|V|jsdSdS)Nr)rBpoprCrAformatrrrr__iter__s  zLogBuffer.__iter__cCs|j|dSr)rBappendrrrrrr9zLogBuffer.emitN)F)rrr __doc__rrErHrrrrrr?s    r?c@r ) _StdoutLoggercCs(tjj|t|dtjddd|_dS)Nrr r r )rrrr& FormatterrA)rr%rrrrs  z_StdoutLogger.__init__cCst|j|dSr)printrArGrrrrr sz_StdoutLogger.emitNrrrrrrKs rKcCstt|dS)z Logs further events to stdout. :param stem.util.log.Runlevel runlevel: minimum runlevel a message needs to be to be logged N)r" addHandlerrKr$rrr log_to_stdoutsrO).rJrZ stem.prereqr Zstem.util.enumZstem.util.str_toolsr,enumZ UppercaseEnumr6listrrrrrZERRrr#Z addLevelNameZ getLoggerr!ZsetLevelrLr@setr2rrr'rNr"r&r(r0r1r4r8r:r;r<r=r>r?rKrOrrrrsR/        %