+ """Initialize logging for the program. This must be called if you want
+ to use any of the functionality provided by this module such as:
+
+ * Ability to set logging level,
+ * ability to define the logging format,
+ * ability to tee all logging on stderr,
+ * ability to tee all logging into a file,
+ * ability to rotate said file as it grows,
+ * ability to tee all logging into the system log (syslog) and
+ define the facility and level used to do so,
+ * easy automatic pid/tid stamp on logging for debugging threads,
+ * ability to squelch repeated log messages,
+ * ability to log probabilistically in code,
+ * ability to only see log messages from a particular module or
+ function,
+ * ability to clear logging handlers added by earlier loaded modules.
+
+ All of these are controlled via commandline arguments to your program,
+ see the code below for details.
+
+ If you use the
+ :meth:`bootstrap.initialize` decorator on your program's entry point,
+ it will call this for you. See :meth:`python_modules.bootstrap.initialize`
+ for more details.
+ """
+ global LOGGING_INITIALIZED
+ if LOGGING_INITIALIZED:
+ return logging.getLogger()
+ LOGGING_INITIALIZED = True