o i?@sdZddlmZddlmZddlmZddlmZmZm Z m Z m Z m Z ddl mZddlmZdd lmZmZdd lmZmZGd d d e ZGd ddZGdddZGdddZeZdddZdS)z Logger class. ) annotations)time) TracebackType)AnyCallableContextManagerOptionalProtocolcast) currentframe)Failure) ILogObserverLogTrace)InvalidLogLevelErrorLogLevelc@s:eZdZdZed ddZed ddZed d d Zd S) Operationz An L{Operation} represents the success (or lack thereof) of code performed within the body of the L{Logger.failureHandler} context manager. returnboolcCdS)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. Nselfrr\C:\Users\psant\Downloads\PAF backend\school\venv\Lib\site-packages\twisted/logger/_logger.py succeededzOperation.succeededFailure | NonecCr)zj Did the operation raise an exception? If so, this L{Failure} is that exception. Nrrrrrfailure#rzOperation.failurecCr)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. Nrrrrrfailed*rzOperation.failedNrr)rr)__name__ __module__ __qualname____doc__propertyrrrrrrrrs  rc@sReZdZUdZded<dZded<dd d Zedd dZdddZ dddZ dS) _FailCtxMgrFrrNrrfailCallable[[Failure], None]rNonecC ||_dSN_failrr&rrr__init__7 z_FailCtxMgr.__init__cCs |jduSr*rrrrrr:s z_FailCtxMgr.failedrcCs|Sr*rrrrr __enter__>z_FailCtxMgr.__enter__exc_typetype[BaseException] | None exc_valueBaseException | None tracebackTracebackType | NonecCs,|durt}||_||dSd|_dSNT)r rr,rrr3r5r7rrrr__exit__As z_FailCtxMgr.__exit__r&r'rr(r)rrr3r4r5r6r7r8rr) r r!r"r__annotations__rr.r$rr1r;rrrrr%3s     r%c@s*eZdZdddZdddZdddZdS)_FastFailCtxMgrr&r'rr(cCr)r*r+r-rrrr.Rr/z_FastFailCtxMgr.__init__cCsdSr*rrrrrr1Ur2z_FastFailCtxMgr.__enter__r3r4r5r6r7r8rcCs"|durt}||_||dSr9)r rr,r:rrrr;Xs  z_FastFailCtxMgr.__exit__Nr<)rr(r=)r r!r"r.r1r;rrrrr?Qs  r?c@seZdZdZed4ddZ   d5d6ddZd7d8ddZd4ddZ d7d9ddZ de j fd:d!d"Z d7d;d#d$Z d7d;d%d&Zd7d;d'd(Zd7d;d)d*Zd7d;d+d,Z e j fdLoggera~ 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. rstrcCs,z tttdjdWStyYdSw)z Derive a namespace from the module containing the caller's caller. @return: the fully qualified python name of a module. r z N)r rAr f_globalsKeyErrorrrrr_namespaceFromCallingContextqs  z#Logger._namespaceFromCallingContextN namespace Optional[str]sourceOptional[object]observerOptional['ILogObserver']r(cCsD|dur|}||_||_|durddlm}||_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)rErFrHZ_globalrLrJ)rrFrHrJrLrrrr.}s   zLogger.__init__instanceobjectownerOptional[type]'Logger'cCs>|dusJ|dur |}n|}|jd|j|jg||jdS)a When used as a descriptor, i.e.:: # File: athing.py class Something: log = Logger() def hello(self): self.log.info("Hello") a L{Logger}'s namespace will be set to the name of the class it is declared on. In the above example, the namespace would be C{athing.Something}. Additionally, its source will be set to the actual object referring to the L{Logger}. In the above example, C{Something.log.source} would be C{Something}, and C{Something().log.source} would be an instance of C{Something}. N.)rJ) __class__joinr!r rJ)rrMrOrHrrr__get__s zLogger.__get__cCsd|jjd|jdS)N< >)rSr rFrrrr__repr__szLogger.__repr__levelrformatkwargscKsz|tvr|jdtt|||ddS|}|j|||j|j|tdd|vr6t t |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().)Z invalidLevelloggerN)Z log_logger log_levelZ log_namespaceZ log_sourceZ log_formatZlog_timeZ log_trace) rZ iterconstantsrr rupdaterFrHrr rappendrJ)rrZr[r\eventrrremits(   z Logger.emitrOptional[Failure]cKs*|durt}|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} NZ log_failure)r rb)rr[rrZr\rrrrs2zLogger.failurecK|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)rbrdebugrr[r\rrrre z Logger.debugcKrd)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)rbrinforfrrrrh*rgz Logger.infocKrd)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)rbrwarnrfrrrri9rgz Logger.warncKrd)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)rbrerrorrfrrrrjHrgz Logger.errorcKrd)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)rbrcriticalrfrrrrkWrgzLogger.criticalContextManager[Operation]c stfddS)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. csj|fiSr*r0fr[r\rZrrrsz(Logger.failuresHandled..N)r%)rr[rZr\rrorfailuresHandledfs*zLogger.failuresHandled staticMessageContextManager[None]cstfddS)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. cs|Sr*r0rmrZrrrrrrpsz'Logger.failureHandler..N)r?)rrrrZrrtrfailureHandlers+zLogger.failureHandler)rrA)NNN)rFrGrHrIrJrKrr(r*)rMrNrOrPrrQ)rZrr[rGr\rNrr() r[rArrcrZrr\rNrr()r[rGr\rNrr()r[rArZrr\rNrrl)rrrArZrrrs)r r!r"r# staticmethodrEr.rUrYrbrrkrrerhrirjrqrurrrrr@fs0     * 7     /r@objrNrcCst||jS)z? Get a L{Logger} instance attached to the given class. N)_logrUrS)rwrrr _loggerForsryN)rwrNrr@)r# __future__rrtypesrtypingrrrrr r Ztwisted.python.compatr Ztwisted.python.failurer Z _interfacesrrZ_levelsrrrr%r?r@rxryrrrrs"      \