tf? dZddlmZddlmZddlmZddlmZmZm Z m Z m Z m Z ddl mZddlmZdd lmZmZdd lmZmZGd d e ZGd dZGddZGddZeZddZdS)z Logger class. ) annotations)time) TracebackType)AnyCallableContextManagerOptionalProtocolcast) currentframe)Failure) ILogObserverLogTrace)InvalidLogLevelErrorLogLevelcZeZdZdZed dZed dZed dZdS) Operationz An L{Operation} represents the success (or lack thereof) of code performed within the body of the L{Logger.failureHandler} context manager. returnboolcdS)z Did the operation succeed? C{True} iff the code completed without raising an exception; C{False} while the code is running and C{False} if it raises an exception. Nselfs U/var/www/surfInsights/venv3-11/lib/python3.11/site-packages/twisted/logger/_logger.py succeededzOperation.succeededFailure | NonecdS)zj Did the operation raise an exception? If so, this L{Failure} is that exception. Nrrs rfailurezOperation.failure#rrcdS)z Did the operation fail? C{True} iff the code raised an exception; C{False} while the code is running and C{False} if it completed without error. Nrrs rfailedzOperation.failed*rrNrr)rr)__name__ __module__ __qualname____doc__propertyrr!r#rrrrrs~    X    X    X   rrc\eZdZUdZded<dZded<dd Zedd ZddZ ddZ dS) _FailCtxMgrFrrNrr!failCallable[[Failure], None]rNonec||_dSN_failrr,s r__init__z_FailCtxMgr.__init__7  rc|jduSr0r!rs rr#z_FailCtxMgr.failed:s|4''rrc|Sr0rrs r __enter__z_FailCtxMgr.__enter__>s rexc_typetype[BaseException] | None exc_valueBaseException | None tracebackTracebackType | Nonecn|+t}||_||nd|_dSNT)r r!r2rrr:r<r>r!s r__exit__z_FailCtxMgr.__exit__As;  iiG"DL JJw    !DNtrr,r-rr.r$)rrr:r;r<r=r>r?rr) r%r&r'r__annotations__r!r4r)r#r9rCrrrr+r+3sI"G""""(((X(      rr+c&eZdZddZddZddZdS)_FastFailCtxMgrr,r-rr.c||_dSr0r1r3s rr4z_FastFailCtxMgr.__init__Rr5rcdSr0rrs rr9z_FastFailCtxMgr.__enter__Us rr:r;r<r=r>r?rc^|*t}||_||dSrA)r r!r2rBs rrCz_FastFailCtxMgr.__exit__Xs1  iiG"DL JJw   trNrD)rr.rE)r%r&r'r4r9rCrrrrHrHQsP          rrHceZdZdZed'dZ d(d)d Zd*d+dZd'dZ d*d,dZ de j fd-dZ d*d.dZ d*d.dZd*d.dZd*d.d Zd*d.d!Z e j fd/d#Ze j fd0d&ZdS)1Loggera~ A L{Logger} emits log messages to an observer. You should instantiate it as a class or module attribute, as documented in L{this module's documentation }. @ivar namespace: the namespace for this logger @ivar source: The object which is emitting events via this logger @ivar observer: The observer that this logger will send events to. rstrc tttdjdS#t$rYdSwxYw)z Derive a namespace from the module containing the caller's caller. @return: the fully qualified python name of a module. r%z )r rNr f_globalsKeyErrorrrr_namespaceFromCallingContextz#Logger._namespaceFromCallingContextqsG \!__6zBCC C   ;; s ,/ ==N namespace Optional[str]sourceOptional[object]observerOptional['ILogObserver']r.c~||}||_||_|ddlm}||_dS||_dS)a3 @param namespace: The namespace for this logger. Uses a dotted notation, as used by python modules. If not L{None}, then the name of the module of the caller is used. @param source: The object which is emitting events via this logger; this is automatically set on instances of a class if this L{Logger} is an attribute of that class. @param observer: The observer that this logger will send events to. If L{None}, use the L{global log publisher }. Nr)globalLogPublisher)rSrTrV_globalr[rX)rrTrVrXr[s rr4zLogger.__init__}sW  99;;I"   3 3 3 3 3 3*)rdr%rTrs r__repr__zLogger.__repr__s"@4>*@@T^@@@@rlevelrformatkwargsc |tjvr5|dtt |||dS|}||||j|j|td|vr5tt|d ||j f| |dS)a Emit a log event to all log observers at the given level. @param level: a L{LogLevel} @param format: a message format using new-style (PEP 3101) formatting. The logging event (which is a L{dict}) is used to render this format string. @param kwargs: additional key/value pairs to include in the event. Note that values which are later mutated may result in non-deterministic behavior from observers that schedule work for later execution. z:Got invalid log level {invalidLevel!r} in {logger}.emit().) invalidLevelloggerN) log_logger log_level log_namespace log_source log_formatlog_time log_trace) r iterconstantsr!r rupdaterTrVrr rappendrX)rrlrmrnevents remitz Logger.emits .00 0 0 LLL,U3344"     F .{VV     %   5- . . 5 5tT]6K L L L err!Optional[Failure]c H|t}|j||fd|i|dS)am Log a failure and emit a traceback. For example:: try: frob(knob) except Exception: log.failure("While frobbing {knob}", knob=knob) or:: d = deferredFrob(knob) d.addErrback(lambda f: log.failure("While frobbing {knob}", f, knob=knob)) This method is meant to capture unexpected exceptions in code; an exception that is caught and handled somehow should be logged, if appropriate, via L{Logger.error} instead. If some unknown exception occurs and your code doesn't know how to handle it, as in the above example, then this method provides a means to describe the failure. This is done at L{LogLevel.critical} by default, since no corrective guidance can be offered to an user/administrator, and the impact of the condition is unknown. @param format: a message format using new-style (PEP 3101) formatting. The logging event (which is a L{dict}) is used to render this format string. @param failure: a L{Failure} to log. If L{None}, a L{Failure} is created from the exception in flight. @param level: a L{LogLevel} to use. @param kwargs: additional key/value pairs to include in the event. Note that values which are later mutated may result in non-deterministic behavior from observers that schedule work for later execution. @see: L{Logger.failureHandler} @see: L{Logger.failuresHandled} N log_failure)r r})rrmr!rlrns rr!zLogger.failures:d ?iiG %??W??????rc 8|jtj|fi|dS)a Emit a log event at log level L{LogLevel.debug}. @param format: a message format using new-style (PEP 3101) formatting. The logging event (which is a L{dict}) is used to render this format string. @param kwargs: additional key/value pairs to include in the event. Note that values which are later mutated may result in non-deterministic behavior from observers that schedule work for later execution. N)r}rdebugrrmrns rrz Logger.debug(  (.&33F33333rc 8|jtj|fi|dS)a Emit a log event at log level L{LogLevel.info}. @param format: a message format using new-style (PEP 3101) formatting. The logging event (which is a L{dict}) is used to render this format string. @param kwargs: additional key/value pairs to include in the event. Note that values which are later mutated may result in non-deterministic behavior from observers that schedule work for later execution. N)r}rinfors rrz Logger.info*(  (-22622222rc 8|jtj|fi|dS)a Emit a log event at log level L{LogLevel.warn}. @param format: a message format using new-style (PEP 3101) formatting. The logging event (which is a L{dict}) is used to render this format string. @param kwargs: additional key/value pairs to include in the event. Note that values which are later mutated may result in non-deterministic behavior from observers that schedule work for later execution. N)r}rwarnrs rrz Logger.warn9rrc 8|jtj|fi|dS)a Emit a log event at log level L{LogLevel.error}. @param format: a message format using new-style (PEP 3101) formatting. The logging event (which is a L{dict}) is used to render this format string. @param kwargs: additional key/value pairs to include in the event. Note that values which are later mutated may result in non-deterministic behavior from observers that schedule work for later execution. N)r}rerrorrs rrz Logger.errorHrrc 8|jtj|fi|dS)a Emit a log event at log level L{LogLevel.critical}. @param format: a message format using new-style (PEP 3101) formatting. The logging event (which is a L{dict}) is used to render this format string. @param kwargs: additional key/value pairs to include in the event. Note that values which are later mutated may result in non-deterministic behavior from observers that schedule work for later execution. N)r}rcriticalrs rrzLogger.criticalWs)  (#V66v66666rContextManager[Operation]c 4tfdS)a/ Run some application code, logging a failure and emitting a traceback in the event that any of it fails, but continuing on. For example:: log = Logger(...) def frameworkCode() -> None: with log.failuresHandled("While frobbing {knob}:", knob=knob) as op: frob(knob) if op.succeeded: log.info("frobbed {knob} successfully", knob=knob) This method is meant to capture unexpected exceptions from application code; an exception that is caught and handled somehow should be logged, if appropriate, via L{Logger.error} instead. If some unknown exception occurs and your code doesn't know how to handle it, as in the above example, then this method provides a means to describe the failure. This is done at L{LogLevel.critical} by default, since no corrective guidance can be offered to an user/administrator, and the impact of the condition is unknown. @param format: a message format using new-style (PEP 3101) formatting. The logging event (which is a L{dict}) is used to render this format string. @param level: a L{LogLevel} to use. @param kwargs: additional key/value pairs to include in the event, if it is emitted. Note that values which are later mutated may result in non-deterministic behavior from observers that schedule work for later execution. @see: L{Logger.failure} @see: L{Logger.failureHandler} @return: A context manager which yields an L{Operation} which will have either its C{succeeded} or C{failed} attribute set to C{True} upon completion of the code within the code within the C{with} block. c$j|fiSr0r7)frmrnrlrs rz(Logger.failuresHandled..s\T\&!U%M%Mf%M%Mr)r+)rrmrlrns````rfailuresHandledzLogger.failuresHandledfs*TMMMMMMMNNNr staticMessageContextManager[None]c0tfdS)a For performance-sensitive frameworks that needs to handle potential failures from frequently-called application code, and do not need to include detailed structured information about the failure nor inspect the result of the operation, this method returns a context manager that will log exceptions and continue, that can be shared across multiple invocations. It should be instantiated at module scope to avoid additional object creations. For example:: log = Logger(...) ignoringFrobErrors = log.failureHandler("while frobbing:") def hotLoop() -> None: with ignoringFrobErrors: frob() This method is meant to capture unexpected exceptions from application code; an exception that is caught and handled somehow should be logged, if appropriate, via L{Logger.error} instead. If some unknown exception occurs and your code doesn't know how to handle it, as in the above example, then this method provides a means to describe the failure in nerd-speak. This is done at L{LogLevel.critical} by default, since no corrective guidance can be offered to an user/administrator, and the impact of the condition is unknown. @param format: a message format using new-style (PEP 3101) formatting. The logging event (which is a L{dict}) is used to render this format string. @param level: a L{LogLevel} to use. @see: L{Logger.failure} @return: A context manager which does not return a value, but will always exit from exceptions. c2|Sr0r7)rrlrrs rrz'Logger.failureHandler..smQ)N)Nr)rH)rrrls```rfailureHandlerzLogger.failureHandlers&VNNNNNNOOOr)rrN)NNN)rTrUrVrWrXrYrr.r0)r]r^r_r`rra)rlrrmrUrnr^rr.) rmrNr!r~rlrrnr^rr.)rmrUrnr^rr.)rmrNrlrrnr^rr)rrNrlrrr)r%r&r'r( staticmethodrSr4rfrkr}rrr!rrrrrrrrrrMrMfs   \ $(#'-1 %%%%%:     @AAAA8<%%%%%T&*"+ 5@5@5@5@5@n 4 4 4 4 4 3 3 3 3 3 3 3 3 3 3 4 4 4 4 4 7 7 7 7 7 .6->*O*O*O*O*O^#++P+P+P+P+P+P+PrrMobjr^rcBt||jS)z? Get a L{Logger} instance attached to the given class. )_logrfrd)rs r _loggerForrs <<S] + ++rN)rr^rrM)r( __future__rrtypesrtypingrrrr r r twisted.python.compatr twisted.python.failurer _interfacesrr_levelsrrrr+rHrMrrrrrrs #"""""JJJJJJJJJJJJJJJJ......******////////33333333        <<*WPWPWPWPWPWPWPWPt vxx,,,,,,r