docs: def trace(_name):
      """Function decorator that logs function entry and exit details.
  
      \var{_name} a string, an instance of logging.Logger or a function.
  
      Construct a function or method proxy to generate call traces.
      """
      def decorator(_func):
          """This is the actual decorator function that wraps the
          \var{_func} function for detailed logging.
          """
  
          def positional(name, value):
              """Format one named positional argument.
              """
              if name is __self:
                  return af_self(name, value)
              elif name is __klass:
                  return af_class(name, value)
              else:
                  return af_named(name, value)
  
          def wrapper(*__argv, **__kwds):
              if not logger.isEnabledFor(logging.DEBUG) or _.value:
                  return _func(*__argv, **__kwds)
  
              try:
                  _.value = True
                  params = dict(co_defaults)
                  params.update(__kwds)
                  params.update(zip(co_varnames, __argv))
                  if 'raw_password' in params:
                      params['raw_password'] = '<censored>'
  
                  position = [
                      positional(n, params.pop(n))
                      for n in co_varnames[:len(__argv)]
                  ]
                  defaults = [
                      af_default(n, params.pop(n))
                      for n in co_varnames[len(__argv):]
                  ]
                  nameless = (
                      af_unnamed(v) for v in __argv[co_argcount:]
                  )
                  keywords = (
                      af_keyword(n, params[n]) for n in sorted(params.keys())
                  )
  
                  params = ', '.join(
                      filter(None, chain(
                          position,
                          defaults,
                          nameless,
                          keywords)))
                  # params = params.replace(', [', '[, ').replace('][, ', ', ')
  
                  enter = [pre_enter]
                  if params:
                      enter.append(' ')
                      enter.append(params)
                      enter.append(' ')
                  enter.append(')')
  
                  leave = [pre_leave]
  
                  try:
                      logger.debug(''.join(enter))
                      try:
                          try:
                              _.value = False
                              result = _func(*__argv, **__kwds)
                          finally:
                              _.value = True
                      except Exception:
                          ex_type, value, traceback = sys.exc_info()
                          leave.append(' => exception thrown\n\traise ')
                          __mname = ex_type.__module__
                          if __mname != '__main__':
                              leave.append(__mname)
                              leave.append('.')
                          leave.append(ex_type.__name__)
                          if value.args:
                              leave.append('(')
                              leave.append(
                                  ', '.join(chop(v) for v in value.args))
                              leave.append(')')
                          else:
                              leave.append('()')
                          raise
                      else:
                          if result is not None:
                              leave.append(' => ')
                              leave.append(chop(result))
                  finally:
                      logger.debug(''.join(leave))
              finally:
                  _.value = False
  
              return result
  
          ####
          #  decorator
          ####
  
          __self = False
          __klass = False
  
          def nop(x):
              return x
  
          __rewrap = nop
          if type(_func) in FunctionTypes:
              # functions do not belong to a class.
              __cname = None
          elif type(_func) in MethodTypes:
              # im_self is None for unbound instance methods.
              # Assumption: trace is only called on unbound methods.
              if _func.im_self is not None:
                  __rewrap = classmethod
                  __cname = _func.im_self.__name__
                  __klass = True
              else:
                  __cname = _func.im_class.__name__
                  __self = True
              _func = _func.im_func
          else:
              # other callables are not supported yet.
              return _func
          __module = _func.__module__
          __fname = _func.__name__
  
          # Do not wrap initialization and conversion methods.
          if __fname in ('__init__', '__new__', '__repr__', '__str__'):
              return __rewrap(_func)
  
          # Generate the Fully Qualified Function Name.
  
          __fqfn = list()
          if __module != '__main__':
              __fqfn.append(__module)
              __fqfn.append('.')
          if __cname is not None:
              __fqfn.append(__cname)
              __fqfn.append('.')
          __fqfn.append(__fname)
          __fqfn = ''.join(__fqfn)
  
          if type(_name) in CallableTypes:
              logger = get_logger_factory().get_logger(__fqfn)
          elif loggable(_name):
              logger = _name
          elif isinstance(_name, six.string_types):
              logger = get_logger_factory().get_logger(_name)
          else:
              raise ValueError(
                  'invalid object %r: must be a function, a method, '
                  'a string or an object that implements the Logger API' % _name)
  
          pre_enter = ['>>> ', __fqfn, '(']
          pre_enter = ''.join(pre_enter)
  
          pre_leave = ['<<< ', __fqfn]
          pre_leave = ''.join(pre_leave)
  
          ####
          #  Here we are really mucking around in function internals.
          #  func_code is the low level 'code' instance that describes
          #  the function arguments, variable and other stuff.
          #
          #  func.func_code.co_argcount - number of function arguments.
          #  func.func_code.co_varnames - function variables names, the
          #      first co_argcount values are the argument names.
          #  func.func_defaults - contains default arguments
  
          try:
              code = _func.__code__
          except AttributeError:
              co_argcount, co_varnames, co_defaults = \
                  __lookup_builtin(_func.__name__)
          else:
              co_argcount = code.co_argcount
              co_varnames = code.co_varnames[:co_argcount]
              if _func.__defaults__:
                  co_defaults = dict(
                      zip(co_varnames[-len(_func.__defaults__):],
                          _func.__defaults__))
              else:
                  co_defaults = dict()
              if __klass:
                  __klass = co_varnames[0]
              if __self:
                  __self = co_varnames[0]
          return __rewrap(wraps(_func)(wrapper))
  
      ####
      #  trace
      ####
  
  #    logging.basicConfig(level = logging.DEBUG)
      if type(_name) in CallableTypes:
          return decorator(_name)
      else:
          return decorator