Commits

Can Xue  committed 5650b4b

change doc strings and comments to English

  • Participants
  • Parent commits 6a5f32c

Comments (0)

Files changed (1)

File kahgean/logkit.py

-# -*- coding: utf-8 -*-
 # Copyright (C) 2012 Xue Can <xuecan@gmail.com> and contributors.
 # Licensed under the MIT license: http://www.opensource.org/licenses/mit-license
 
+"""\
+kahgean.logkit
+==============
+
+``kahgean.logkit`` is a handy tools for developers to config logging
+for their programs written in Python.
+
+It's just a set of command-line and configuration file options definition,
+and if a progeam will log to ``stderr``, try to make the result be colorful.
+"""
+
+
 import os
 import sys
 import logging
 import logging.handlers
 
 if os.name=='nt':
-    # 对于 Windows,我们需要 colorama 支持在 stderr 以不同颜色显示日志
+    # we need colorama for colored text under Microsoft Windows
+    # for more information about colorama, please visit:
+    # http://pypi.python.org/pypi/colorama
     try:
         from colorama import AnsiToWin32
     except ImportError:
         AnsiToWin32 = None
 
-# Ansi 颜色控制码
+# ANSI escape code for colors
+# visit http://en.wikipedia.org/wiki/ANSI_escape_code#Colors for more
 CSI_PATTERN = '\033[%dm'
 (FORE_BLACK, FORE_RED, FORE_GREEN, FORE_YELLOW, FORE_BLUE, FORE_MAGENTA,
  FORE_CYAN, FORE_WHITE, _, FORE_RESET) = range(30, 40)
 
 CSI = lambda code: CSI_PATTERN % code
 
-# 默认的日志格式和日志时间格式
+# default log and date format
 DEFAULT_FORMAT = '[%(asctime)s %(name)8.8s %(levelname)1.1s] %(message)s'
 DEFAULT_DATE_FORMAT = '%y%m%d %H:%M:%S'
 
         self.colored = bool(colored)
                 
     def format(self, record):
-        # 正常的日志信息
+        # common log record information
         record.message = record.getMessage()
         if self.usesTime():
             record.asctime = self.formatTime(record, self.datefmt)
         s = self._fmt % record.__dict__
-        # 颜色控制
+        # colors
         if self.colored:
             if record.levelno == logging.DEBUG:
                 prefix = CSI(BRIGHT)+CSI(FORE_CYAN)
             else:
                 prefix = CSI(RESET_ALL)
             s = prefix + s + CSI(RESET_ALL)
-        # 如果需要,加上异常信息
+        # append exception information if needed
         if record.exc_info:
             # Cache the traceback text to avoid converting it multiple times
             # (it's constant anyway)
 
 
 def add_options(options):
-    """配合 options 模块使用,方便添加和本模块有关的配置参数"""
+    """work with kahgean.options, add arguments to an ``Options`` object"""
     options.add_option('--log-level', help='logging level (default: info)')
     options.add_option('--log-format', help='')
     options.add_option('--log-date-format', help='')
-    options.add_option('--log-to-stderr', help='')
+    options.add_option('--log-to-stderr', help='', default=None)
     options.add_option('--log-filename', help='')
     options.add_option('--log-server', help='')
 
 
 def deal_with_options(options):
-    """配合 add_options() 使用,分析参数并进行相应操作"""
+    """work with ``add_options()``, deal with the parsing result of
+    the ``Options`` object"""
     root_logger = logging.getLogger()
-    # 将日志等级设置在 root 日志器上
-    level_name = options.get('log_level') or 'info'
+    # setup log level
+    level_name = options.get('log_level', 'info')
     root_logger.setLevel(level_name.upper())
-
-    # 读取日志格式设置信息
-    format = options.get('log_format') or DEFAULT_FORMAT
-    date_format = options.get('date_format') or DEFAULT_DATE_FORMAT
-
-    # 如果配置了 log_filename,则启用基于文件的日志处理器
-    log_filename = options.get('log_filename')
+    # setup formats
+    format = options.get('log_format', DEFAULT_FORMAT)
+    date_format = options.get('date_format', DEFAULT_DATE_FORMAT)
+    # if log_filename is given, use a file-based handler
+    log_filename = options.get('log_filename', None)
     if log_filename:
         handler = logging.FileHandler(log_filename, encoding='utf8')
         formatter = ColoredFormatter(False, format, date_format)
         handler.setFormatter(formatter)
         root_logger.addHandler(handler)
-    
-    # 如果配置了 log_server,则启用基于 socket 的日志处理器
-    log_server = options.get('log_server')
+    # if log_server is given, use a socket-based handler
+    log_server = options.get('log_server', None)
     if log_server:
         info = log_server.split(':', 1)
         if len(info) == 2:
-            # 形如 address:port 的情况
+            # for ``address:port``
             host, port = info
             port = int(info)
         else:
             port = logging.handlers.DEFAULT_TCP_LOGGING_PORT
         handler = SocketHandler(host, port)
         root_logger.addHandler(handler)
-
-    # 如果允许在 stderr 写入日志(或者是设置了 log_to_stderr 为 True,或者
-    # log_to_stderr 为 None 但 root 日志器没有配置任何日志处理器),则尝试
-    # 使用颜色表示不同的等级。在 Windows 下,需要借助第三方模块 colorama
-    # 来转换 ANSI 颜色控制序列
-    log_to_stderr = options.get('log_to_stderr')
+    # if use stderr to log (either log_to_stderr is True, or no any handlers
+    # have been registered to the root logger), try to make log text colorful
+    log_to_stderr = options.get('log_to_stderr', None)
     if log_to_stderr or (log_to_stderr is None and not root_logger.handlers):
         stderr = sys.stderr
         colored = True