class_docstr: Handler for logging to a set of files, which switches from one file to the
  next when the current file reaches a certain size. Multiple processes can
  write to the log file concurrently, but this may mean that the file will
  exceed the given size.
class_docstr_tok: ["Handler","for","logging","to","a","set","of","files",",","which","switches","from","one","file","to","the","next","when","the","current","file","reaches","a","certain","size",".","Multiple","processes","can","write","to","the","log","file","concurrently",",","but","this","may","mean","that","the","file","will","exceed","the","given","size","."]
docstr: Open the specified file and use it as the stream for logging.
  
  By default, the file grows indefinitely. You can specify particular
  values of maxBytes and backupCount to allow the file to rollover at
  a predetermined size.
  
  Rollover occurs whenever the current log file is nearly maxBytes in
  length. If backupCount is >= 1, the system will successively create
  new files with the same pathname as the base file, but with extensions
  ".1", ".2" etc. appended to it. For example, with a backupCount of 5
  and a base file name of "app.log", you would get "app.log",
  "app.log.1", "app.log.2", ... through to "app.log.5". The file being
  written to is always "app.log" - when it gets filled up, it is closed
  and renamed to "app.log.1", and if files "app.log.1", "app.log.2" etc.
  exist, then they are renamed to "app.log.2", "app.log.3" etc.
  respectively.
  
  If maxBytes is zero, rollover never occurs.
  
  On Windows, it is not possible to rename a file that is currently opened
  by another process.  This means that it is not possible to rotate the
  log files if multiple processes is using the same log file.  In this
  case, the current log file will continue to grow until the rotation can
  be completed successfully.  In order for rotation to be possible, all of
  the other processes need to close the file first.  A mechanism, called
  "degraded" mode, has been created for this scenario.  In degraded mode,
  the log file is closed after each log message is written.  So once all
  processes have entered degraded mode, the next rotate log attempt should
  be successful and then normal logging can be resumed.
  
  This log handler assumes that all concurrent processes logging to a
  single file will are using only this class, and that the exact same
  parameters are provided to each instance of this class.  If, for
  example, two different processes are using this class, but with
  different values for 'maxBytes' or 'backupCount', then odd behavior is
  expected. The same is true if this class is used by one application, but
  the RotatingFileHandler is used by another.
  
  NOTE:  You should always provide 'filename' as an absolute path, since
  this class will need to re-open the file during rotation. If your
  application call os.chdir() then subsequent log files could be created
  in the wrong directory.
docstr_tok: ["Open","the","specified","file","and","use","it","as","the","stream","for","logging",".","By","default",",","the","file","grows","indefinitely",".","You","can","specify","particular","values","of","maxBytes","and","backupCount","to","allow","the","file","to","rollover","at","a","predetermined","size",".","Rollover","occurs","whenever","the","current","log","file","is","nearly","maxBytes","in","length",".","If","backupCount","is",">","=","1",",","the","system","will","successively","create","new","files","with","the","same","pathname","as","the","base","file",",","but","with","extensions","''",".1","''",",","``",".2","''","etc",".","appended","to","it",".","For","example",",","with","a","backupCount","of","5","and","a","base","file","name","of","``","app.log","''",",","you","would","get","``","app.log","''",",","''","app.log.1","''",",","``","app.log.2","''",",","...","through","to","``","app.log.5","''",".","The","file","being","written","to","is","always","``","app.log","''","-","when","it","gets","filled","up",",","it","is","closed","and","renamed","to","``","app.log.1","''",",","and","if","files","``","app.log.1","''",",","``","app.log.2","''","etc",".","exist",",","then","they","are","renamed","to","``","app.log.2","''",",","``","app.log.3","''","etc",".","respectively",".","If","maxBytes","is","zero",",","rollover","never","occurs",".","On","Windows",",","it","is","not","possible","to","rename","a","file","that","is","currently","opened","by","another","process",".","This","means","that","it","is","not","possible","to","rotate","the","log","files","if","multiple","processes","is","using","the","same","log","file",".","In","this","case",",","the","current","log","file","will","continue","to","grow","until","the","rotation","can","be","completed","successfully",".","In","order","for","rotation","to","be","possible",",","all","of","the","other","processes","need","to","close","the","file","first",".","A","mechanism",",","called","''","degraded","''","mode",",","has","been","created","for","this","scenario",".","In","degraded","mode",",","the","log","file","is","closed","after","each","log","message","is","written",".","So","once","all","processes","have","entered","degraded","mode",",","the","next","rotate","log","attempt","should","be","successful","and","then","normal","logging","can","be","resumed",".","This","log","handler","assumes","that","all","concurrent","processes","logging","to","a","single","file","will","are","using","only","this","class",",","and","that","the","exact","same","parameters","are","provided","to","each","instance","of","this","class",".","If",",","for","example",",","two","different","processes","are","using","this","class",",","but","with","different","values","for","'maxBytes","'","or","'backupCount","'",",","then","odd","behavior","is","expected",".","The","same","is","true","if","this","class","is","used","by","one","application",",","but","the","RotatingFileHandler","is","used","by","another",".","NOTE",":","You","should","always","provide","'filename","'","as","an","absolute","path",",","since","this","class","will","need","to","re-open","the","file","during","rotation",".","If","your","application","call","os.chdir","(",")","then","subsequent","log","files","could","be","created","in","the","wrong","directory","."]
code: def __init__(
      self,
      filename,
      mode="a",
      maxBytes=0,
      backupCount=0,
      encoding=None,
      debug=True,
      supress_abs_warn=False,
  ):
      """
      Open the specified file and use it as the stream for logging.
  
      By default, the file grows indefinitely. You can specify particular
      values of maxBytes and backupCount to allow the file to rollover at
      a predetermined size.
  
      Rollover occurs whenever the current log file is nearly maxBytes in
      length. If backupCount is >= 1, the system will successively create
      new files with the same pathname as the base file, but with extensions
      ".1", ".2" etc. appended to it. For example, with a backupCount of 5
      and a base file name of "app.log", you would get "app.log",
      "app.log.1", "app.log.2", ... through to "app.log.5". The file being
      written to is always "app.log" - when it gets filled up, it is closed
      and renamed to "app.log.1", and if files "app.log.1", "app.log.2" etc.
      exist, then they are renamed to "app.log.2", "app.log.3" etc.
      respectively.
  
      If maxBytes is zero, rollover never occurs.
  
      On Windows, it is not possible to rename a file that is currently opened
      by another process.  This means that it is not possible to rotate the
      log files if multiple processes is using the same log file.  In this
      case, the current log file will continue to grow until the rotation can
      be completed successfully.  In order for rotation to be possible, all of
      the other processes need to close the file first.  A mechanism, called
      "degraded" mode, has been created for this scenario.  In degraded mode,
      the log file is closed after each log message is written.  So once all
      processes have entered degraded mode, the next rotate log attempt should
      be successful and then normal logging can be resumed.
  
      This log handler assumes that all concurrent processes logging to a
      single file will are using only this class, and that the exact same
      parameters are provided to each instance of this class.  If, for
      example, two different processes are using this class, but with
      different values for 'maxBytes' or 'backupCount', then odd behavior is
      expected. The same is true if this class is used by one application, but
      the RotatingFileHandler is used by another.
  
      NOTE:  You should always provide 'filename' as an absolute path, since
      this class will need to re-open the file during rotation. If your
      application call os.chdir() then subsequent log files could be created
      in the wrong directory.
      """
      # The question of absolute paths: I'm not sure what the 'right thing' is
      # to do here. RotatingFileHander simply ignores this possibility. I was
      # going call os.path.abspath(), but that potentially limits uses. For
      # example, on Linux (any posix system?) you can rename a directory of a
      # running app, and the app wouldn't notice as long as it only opens new
      # files using relative paths. But since that's not a "normal" thing to
      # do, and having an app call os.chdir() is a much more likely scenario
      # that should be supported. For the moment, we are just going to warn
      # the user if they provide a relative path and do some other voodoo
      # logic that you'll just have to review for yourself.
  
      # if the given filename contains no path, we make an absolute path
      if not os.path.isabs(filename):
          if FORCE_ABSOLUTE_PATH or not os.path.split(filename)[0]:
              filename = os.path.abspath(filename)
          elif not supress_abs_warn:
              from warnings import warn
  
              warn(
                  "The given 'filename' should be an absolute path.  If your "
                  "application calls os.chdir(), your logs may get messed up. "
                  "Use 'supress_abs_warn=True' to hide this message."
              )
      try:
          BaseRotatingHandler.__init__(self, filename, mode, encoding)
      except (
          TypeError
      ):  # Due to a different logging release without encoding support  (Python 2.4.1 and earlier?)
          BaseRotatingHandler.__init__(self, filename, mode)
          self.encoding = encoding
  
      self._rotateFailed = False
      self.maxBytes = maxBytes
      self.backupCount = backupCount
      # Prevent multiple extensions on the lock file (Only handles the normal "*.log" case.)
      self.lock_file = "%s.lock" % filename
      self.stream_lock = SoftFileLock(self.lock_file)
  
      # For debug mode, swap out the "_degrade()" method with a more a verbose one.
      if debug:
          self._degrade = self._degrade_debug
  
file_path: nipype/nipype/external/cloghandler.py
imports: import os
  import sys
  from random import randint
  from logging import Handler
  from logging.handlers import BaseRotatingHandler
  from filelock import SoftFileLock
  import logging.handlers
label_desc: Use image node_id 1 to create a new ConcurrentRotatingFileHandler object from inherited base classes: BaseRotatingHandler with example: obj = ConcurrentRotatingFileHandler(filename, mode, maxBytes, backupCount, encoding, debug, supress_abs_warn)