API Documentation¶
logging facilities
The way to use this is as follows:
each module declares its own logger, using:
from .logger import create_logger logger = create_logger()
then each module uses logger.info/warning/debug/etc according to the level it believes is appropriate:
logger.debug(‘debugging info for developers or power users’) logger.info(‘normal, informational output’) logger.warning(‘warn about a non-fatal error or sth else’) logger.error(‘a fatal error’)
... and so on. see the logging documentation for more information
console interaction happens on stderr, that includes interactive reporting functions like help, info and list
...except
input()
is special, because we can’t control the stream it is using, unfortunately. we assume that it won’t clutter stdout, because interaction would be broken then anywayswhat is output on INFO level is additionally controlled by commandline flags
-
borg.logger.
create_logger
(name=None)[source]¶ lazily create a Logger object with the proper path, which is returned by find_parent_module() by default, or is provided via the commandline
this is really a shortcut for:
logger = logging.getLogger(__name__)we use it to avoid errors and provide a more standard API.
We must create the logger lazily, because this is usually called from module level (and thus executed at import time - BEFORE setup_logging() was called). By doing it lazily we can do the setup first, we just have to be careful not to call any logger methods before the setup_logging() call. If you try, you’ll get an exception.
-
borg.logger.
find_parent_module
()[source]¶ find the name of a the first module calling this module
if we cannot find it, we return the current module’s name (__name__) instead.
-
borg.logger.
setup_logging
(stream=None, conf_fname=None, env_var='BORG_LOGGING_CONF', level='info', is_serve=False)[source]¶ setup logging module according to the arguments provided
if conf_fname is given (or the config file name can be determined via the env_var, if given): load this logging configuration.
otherwise, set up a stream handler logger on stderr (by default, if no stream is provided).
if is_serve == True, we configure a special log format as expected by the borg client log message interceptor.
-
borg.shellpattern.
translate
(pat)[source]¶ Translate a shell-style pattern to a regular expression.
The pattern may include
**<sep>
(<sep> stands for the platform-specific path separator; “/” on POSIX systems) for matching zero or more directory levels and “*” for matching zero or more arbitrary characters with the exception of any path separator. Wrap meta-characters in brackets for a literal match (i.e. “[?]” to match the literal character ”?”).This function is derived from the “fnmatch” module distributed with the Python standard library.
Copyright (C) 2001-2016 Python Software Foundation. All rights reserved.
TODO: support {alt1,alt2} shell-style alternatives