[CalendarServer-changes] [11311] CalendarServer/trunk/twext/python/log.py
source_changes at macosforge.org
source_changes at macosforge.org
Wed Jun 5 16:28:11 PDT 2013
Revision: 11311
http://trac.calendarserver.org//changeset/11311
Author: wsanchez at apple.com
Date: 2013-06-05 16:28:11 -0700 (Wed, 05 Jun 2013)
Log Message:
-----------
Docs.
Modified Paths:
--------------
CalendarServer/trunk/twext/python/log.py
Modified: CalendarServer/trunk/twext/python/log.py
===================================================================
--- CalendarServer/trunk/twext/python/log.py 2013-06-05 21:14:53 UTC (rev 11310)
+++ CalendarServer/trunk/twext/python/log.py 2013-06-05 23:28:11 UTC (rev 11311)
@@ -81,6 +81,9 @@
#
class InvalidLogLevelError(RuntimeError):
+ """
+ Someone tried to use a L{LogLevel} that is unknown to the logging system.
+ """
def __init__(self, level):
super(InvalidLogLevelError, self).__init__(str(level))
self.level = level
@@ -123,9 +126,10 @@
def logLevelForNamespace(namespace):
"""
- @param namespace: a logging namespace, or C{None} to set the
- default log level.
- @return: the log level for the given namespace.
+ @param namespace: a logging namespace, or C{None} for the default
+ namespace.
+
+ @return: the L{LogLevel} for the specified namespace.
"""
if not namespace:
return logLevelsByNamespace[None]
@@ -148,8 +152,10 @@
def setLogLevelForNamespace(namespace, level):
"""
Sets the log level for a logging namespace.
+
@param namespace: a logging namespace
- @param level: the log level for the given namespace.
+
+ @param level: the L{LogLevel} for the given namespace.
"""
if level not in LogLevel.iterconstants():
raise InvalidLogLevelError(level)
@@ -219,19 +225,30 @@
source = type
else:
source = oself
- return self.__class__('.'.join([type.__module__, type.__name__]),
- source)
+ return self.__class__(
+ '.'.join([type.__module__, type.__name__]),
+ source
+ )
+
def __repr__(self):
return "<%s %r>" % (self.__class__.__name__, self.namespace)
def emit(self, level, message=None, **kwargs):
"""
- Called internally to emit log messages at a given log level.
+ Emit a log message to all log observers at the given level.
+
+ @param level: a L{LogLevel}
+
+ @param message: a message
+
+ @param kwargs: additional keyword parameters to include with the
+ message.
"""
- assert level in LogLevel.iterconstants(), "Unknown log level: %r" % (level,)
+ if level not in LogLevel.iterconstants():
+ raise InvalidLogLevelError(level)
# FIXME: Filtering should be done by the log observer(s)
if not self.willLogAtLevel(level):
@@ -271,7 +288,15 @@
def failure(self, failure=None, message=None, **kwargs):
"""
- Log a Failure.
+ Log a failure.
+
+ @param failure: a L{Failure} to log. If C{None}, a L{Failure} is
+ created from the exception in flight.
+
+ @param message: a message
+
+ @param kwargs: additional keyword parameters to include with the
+ message.
"""
if failure is None:
failure=Failure()
@@ -281,31 +306,42 @@
def level(self):
"""
- @return: the logging level for this logger's namespace.
+ @return: the log level for this logger's namespace.
"""
return logLevelForNamespace(self.namespace)
def setLevel(self, level):
"""
- Set the logging level for this logger's namespace.
- @param level: a logging level
+ Set the log level for this logger's namespace.
+
+ @param level: a L{LogLevel}
"""
setLogLevelForNamespace(self.namespace, level)
def willLogAtLevel(self, level):
"""
- @param level: a logging level
- @return: C{True} if this logger will log at the given logging
- level.
+ @param level: a L{LogLevel}
+
+ @return: true if this logger will emit at the given log level,
+ otherwise false.
"""
return self.level() <= level
class LegacyLogger(Logger):
+ """
+ A L{Logger} that provides some compatibility with the L{twisted.python.log}
+ module.
+ """
+
def msg(self, *message, **kwargs):
+ """
+ This method is API-compatible with L{twisted.python.log.msg} and exists
+ for compatibility with that API.
+ """
if message:
message = " ".join(map(safe_str, message))
else:
@@ -314,6 +350,10 @@
def err(self, _stuff=None, _why=None, **kwargs):
+ """
+ This method is API-compatible with L{twisted.python.log.err} and exists
+ for compatibility with that API.
+ """
if _stuff is None:
_stuff = Failure()
elif isinstance(_stuff, Exception):
@@ -332,10 +372,13 @@
def bindEmit(level):
doc = """
- Emit a log message at log level C{%s}.
- @param message: The message to emit.
- """ % (level,)
+ Emit a log message at log level L{%s}.
+ @param message: a message
+
+ @param kwargs: additional keyword parameters to include with the message.
+ """ % (level.__class__.__name__,)
+
#
# Attach methods to Logger
#
@@ -352,6 +395,7 @@
for level in LogLevel.iterconstants():
bindEmit(level)
+
del level
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.macosforge.org/pipermail/calendarserver-changes/attachments/20130605/df4caeff/attachment-0001.html>
More information about the calendarserver-changes
mailing list