wai-logging 0.0.3__tar.gz

wai_logging-0.0.3/CHANGES.rst

@@ -0,0 +1,20 @@
+Changelog
+=========
+
+0.0.3 (2025-01-14)
+------------------
+
+- using underscore in project name now
+
+
+0.0.2 (2025-01-14)
+------------------
+
+- `init_logging` now supports specifying `stream` or `filename` or `handlers` as well as the `log_format`
+
+
+0.0.1 (2023-11-30)
+------------------
+
+- initial release
+

wai_logging-0.0.3/DESCRIPTION.rst

@@ -0,0 +1,8 @@
+Python library with helper methods for logging.
+
+* `init_logging` - initializes the logging with a default level, which can be overridden with an environment variable
+* `set_logging_level` - sets the logging level of a `logging.Logger` instance
+* `str_to_logging_level` - turns a string logging level into a `logging` module one, used by `init_logging` and `set_logging_level`
+* `add_logging_level` - adds an option for the logging level to an `argparse.ArgumentParser` instance
+* `add_logger_name` - adds an option for a custom name for a logger to an `argparse.ArgumentParser` instance
+

wai_logging-0.0.3/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 University of Waikato - Data Mining
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

wai_logging-0.0.3/MANIFEST.in

@@ -0,0 +1,3 @@
+include DESCRIPTION.rst
+include CHANGES.rst
+include LICENSE

wai_logging-0.0.3/PKG-INFO

@@ -0,0 +1,43 @@
+Metadata-Version: 2.1
+Name: wai_logging
+Version: 0.0.3
+Summary: Python library with helper methods for logging.
+Home-page: https://github.com/waikato-datamining/wai-logging
+Author: Peter Reutemann
+Author-email: fracpete@waikato.ac.nz
+License: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Classifier: Programming Language :: Python :: 3
+License-File: LICENSE
+
+Python library with helper methods for logging.
+
+* `init_logging` - initializes the logging with a default level, which can be overridden with an environment variable
+* `set_logging_level` - sets the logging level of a `logging.Logger` instance
+* `str_to_logging_level` - turns a string logging level into a `logging` module one, used by `init_logging` and `set_logging_level`
+* `add_logging_level` - adds an option for the logging level to an `argparse.ArgumentParser` instance
+* `add_logger_name` - adds an option for a custom name for a logger to an `argparse.ArgumentParser` instance
+
+
+Changelog
+=========
+
+0.0.3 (2025-01-14)
+------------------
+
+- using underscore in project name now
+
+
+0.0.2 (2025-01-14)
+------------------
+
+- `init_logging` now supports specifying `stream` or `filename` or `handlers` as well as the `log_format`
+
+
+0.0.1 (2023-11-30)
+------------------
+
+- initial release
+

wai_logging-0.0.3/README.md

@@ -0,0 +1,108 @@
+# wai-logging
+Simple helper library for logging.
+
+
+## Installation
+
+From PyPI:
+
+```bash
+pip install wai_logging
+```
+
+From Github:
+
+```bash
+pip install git+https://github.com/waikato-datamining/wai-logging.git
+```
+
+
+## Methods
+
+The following helper methods are available:
+
+* `init_logging` - initializes the logging with a default level, which can be overridden with an environment variable
+* `set_logging_level` - sets the logging level of a `logging.Logger` instance
+* `str_to_logging_level` - turns a string logging level into a `logging` module one, used by `init_logging` and `set_logging_level`
+* `add_logging_level` - adds an option for the logging level to an `argparse.ArgumentParser` instance
+* `add_logger_name` - adds an option for a custom name for a logger to an `argparse.ArgumentParser` instance
+
+
+## Usage
+
+Below are some examples on how to use the aforementioned methods and what the 
+output may look like. 
+
+### Example 1
+
+The following logging setup only outputs on stderr using a simple format without timestamps: 
+
+```python
+from wai.logging import init_logging, LOGGING_INFO, set_logging_level
+import logging
+
+init_logging(LOGGING_INFO)
+logger = logging.getLogger("my.test")
+set_logging_level(logger, LOGGING_INFO)
+logger.debug("debugging output")
+logger.info("info output")
+logger.warning("warning output")
+```
+
+The output:
+
+```
+INFO:my.test:info output
+WARNING:my.test:warning output
+```
+
+### Example 2
+
+This configuration uses timestamps in its output (`log_format`; see [format strings](https://docs.python.org/3/library/logging.html#logrecord-attributes)) 
+and logs to a file as well (`filename`):
+
+```python
+from wai.logging import init_logging, LOGGING_INFO, set_logging_level, TIMESTAMP_LOG_FORMAT
+import logging
+
+init_logging(LOGGING_INFO, filename="./out.log", log_format=TIMESTAMP_LOG_FORMAT)
+logger = logging.getLogger("my.test")
+set_logging_level(logger, LOGGING_INFO)
+logger.debug("debugging output")
+logger.info("info output")
+logger.warning("warning output")
+```
+
+The output:
+
+```
+2025-01-14 09:25:22,837 - INFO - my.test - info output
+2025-01-14 09:25:22,837 - WARNING - my.test - warning output
+```
+
+### Example 3
+
+The following setup uses a [rotating file handler](https://docs.python.org/3/library/logging.handlers.html#logging.handlers.RotatingFileHandler) 
+and keeps a maximum of three backups (`backupCount`; log files get a numeric suffix like `.1`). 
+A rotation is initiated when the process is restarted and the log file exceeds 100 bytes (`maxBytes`).
+
+```python
+from wai.logging import init_logging, LOGGING_INFO, set_logging_level
+import logging.handlers
+
+init_logging(LOGGING_INFO, handlers=[
+    logging.StreamHandler(), 
+    logging.handlers.RotatingFileHandler(filename="./out.log", backupCount=3, maxBytes=100)])
+logger = logging.getLogger("my.test")
+set_logging_level(logger, LOGGING_INFO)
+logger.debug("debugging output")
+logger.info("info output")
+logger.warning("warning output")
+```
+
+The output:
+
+```
+INFO:my.test:info output
+WARNING:my.test:warning output
+```

wai_logging-0.0.3/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

wai_logging-0.0.3/setup.py

@@ -0,0 +1,38 @@
+from setuptools import setup
+
+
+def _read(f) -> bytes:
+    """
+    Reads in the content of the file.
+    :param f: the file to read
+    :type f: str
+    :return: the content
+    :rtype: str
+    """
+    return open(f, 'rb').read()
+
+
+setup(
+    name="wai_logging",
+    description="Python library with helper methods for logging.",
+    long_description=(
+        _read('DESCRIPTION.rst') + b'\n' +
+        _read('CHANGES.rst')).decode('utf-8'),
+    url="https://github.com/waikato-datamining/wai-logging",
+    classifiers=[
+        'Development Status :: 4 - Beta',
+        'License :: OSI Approved :: MIT License',
+        'Topic :: Scientific/Engineering :: Mathematics',
+        'Programming Language :: Python :: 3',
+    ],
+    license='MIT',
+    package_dir={
+        '': 'src'
+    },
+    packages=[
+        "wai.logging",
+    ],
+    version="0.0.3",
+    author='Peter Reutemann',
+    author_email='fracpete@waikato.ac.nz',
+)

wai_logging-0.0.3/src/wai/logging/__init__.py

@@ -0,0 +1,4 @@
+from ._core import LOGGING_LEVELS, LOGGING_DEBUG, LOGGING_INFO, LOGGING_WARN, LOGGING_WARNING, LOGGING_ERROR, LOGGING_CRITICAL
+from ._core import SIMPLE_LOG_FORMAT, TIMESTAMP_LOG_FORMAT
+from ._core import init_logging, set_logging_level, str_to_logging_level
+from ._argparse import add_logging_level, add_logger_name

wai_logging-0.0.3/src/wai/logging/_argparse.py

@@ -0,0 +1,41 @@
+import argparse
+
+from ._core import LOGGING_LEVELS, LOGGING_WARN
+
+
+def add_logging_level(parser: argparse.ArgumentParser, short_opt: str = "-l", long_opt: str = "--logging_level",
+                      help_str: str = None):
+    """
+    Adds an option for the logging level to the parser.
+
+    :param parser: the parser to append.
+    :type parser: argparse.ArgumentParser
+    :param short_opt: the short option flag to use (eg -l)
+    :type short_opt: str
+    :param long_opt: the long option flag to use (eg --logging_level)
+    :type long_opt: str
+    :param help_str: the help string to use
+    :type help_str: str
+    """
+    if help_str is None:
+        help_str = "The logging level to use."
+    parser.add_argument(short_opt, long_opt, choices=LOGGING_LEVELS, default=LOGGING_WARN, help=help_str)
+
+
+def add_logger_name(parser: argparse.ArgumentParser, short_opt: str = "-N", long_opt: str = "--logger_name",
+                    help_str: str = None):
+    """
+    Adds an option for the logger name to the parser.
+
+    :param parser: the parser to append.
+    :type parser: argparse.ArgumentParser
+    :param short_opt: the short option flag to use (eg -N)
+    :type short_opt: str
+    :param long_opt: the long option flag to use (eg --logger_name)
+    :type long_opt: str
+    :param help_str: the help string to use
+    :type help_str: str
+    """
+    if help_str is None:
+        help_str = "The custom name to use for the logger"
+    parser.add_argument(short_opt, long_opt, type=str, default=None, help=help_str, required=False)

wai_logging-0.0.3/src/wai/logging/_core.py

@@ -0,0 +1,97 @@
+import logging
+import os
+from typing import List, Any
+
+
+LOGGING_DEBUG = "DEBUG"
+LOGGING_INFO = "INFO"
+LOGGING_WARN = "WARN"
+LOGGING_WARNING = "WARNING"
+LOGGING_ERROR = "ERROR"
+LOGGING_CRITICAL = "CRITICAL"
+LOGGING_LEVELS = [
+    LOGGING_DEBUG,
+    LOGGING_INFO,
+    LOGGING_WARNING,
+    LOGGING_ERROR,
+    LOGGING_CRITICAL,
+]
+
+
+SIMPLE_LOG_FORMAT = "%(levelname)s:%(name)s:%(message)s"
+
+TIMESTAMP_LOG_FORMAT = "%(asctime)s - %(levelname)s - %(name)s - %(message)s"
+
+
+def str_to_logging_level(level: str) -> int:
+    """
+    Turns a logging level string into the corresponding integer constant.
+
+    :param level: the level to convert
+    :type level: str
+    :return: the int level
+    :rtype: int
+    """
+    level = level.upper()
+    if level == LOGGING_WARN:
+        level = LOGGING_WARNING
+    if level not in LOGGING_LEVELS:
+        raise Exception("Invalid logging level (%s): %s" % ("|".join(LOGGING_LEVELS), level))
+    if level == LOGGING_CRITICAL:
+        return logging.CRITICAL
+    elif level == LOGGING_ERROR:
+        return logging.ERROR
+    elif level == LOGGING_WARNING:
+        return logging.WARNING
+    elif level == LOGGING_INFO:
+        return logging.INFO
+    elif level == LOGGING_DEBUG:
+        return logging.DEBUG
+    else:
+        raise Exception("Unhandled logging level: %s" % level)
+
+
+def init_logging(default_level: str = LOGGING_WARNING, env_var: str = None, stream: Any = None, filename: str = None,
+                 handlers: List[Any] = None, log_format: str = SIMPLE_LOG_FORMAT):
+    """
+    Initializes the logging.
+
+    :param default_level: the default level to use
+    :type default_level: str
+    :param env_var: the environment variable to check for a level (overrides the default level), ignored if None
+    :type env_var: str
+    :param stream: the stream to use, uses stderr if None (default: None); cannot be used together with 'filename'
+    :param filename: the filename to log to, ignored if None (default: None); cannot be used together with 'stream'
+    :type filename: str
+    :param handlers: the explicit handlers to use
+    :type handlers: list
+    :param log_format: the format string for the logging output
+    :type log_format: str
+    """
+    level = str_to_logging_level(default_level)
+    if env_var is not None:
+        if os.getenv(env_var) is not None:
+            level = str_to_logging_level(os.getenv(env_var))
+    if handlers is None:
+        handlers = []
+        if filename is not None:
+            handlers.append(logging.FileHandler(filename))
+        handlers.append(logging.StreamHandler(stream=stream))
+    else:
+        if stream is not None:
+            raise Exception("Cannot specify 'handlers' and 'stream' together!")
+        if filename is not None:
+            raise Exception("Cannot specify 'handlers' and 'filename' together!")
+    logging.basicConfig(level=level, handlers=handlers, format=log_format)
+
+
+def set_logging_level(logger: logging.Logger, level: str):
+    """
+    Sets the logging level of the logger.
+
+    :param logger: the logger to update
+    :type logger: logging.Logger
+    :param level: the level string, see LOGGING_LEVELS
+    :type level: str
+    """
+    logger.setLevel(str_to_logging_level(level))

wai_logging-0.0.3/src/wai_logging.egg-info/PKG-INFO

@@ -0,0 +1,43 @@
+Metadata-Version: 2.1
+Name: wai-logging
+Version: 0.0.3
+Summary: Python library with helper methods for logging.
+Home-page: https://github.com/waikato-datamining/wai-logging
+Author: Peter Reutemann
+Author-email: fracpete@waikato.ac.nz
+License: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Classifier: Programming Language :: Python :: 3
+License-File: LICENSE
+
+Python library with helper methods for logging.
+
+* `init_logging` - initializes the logging with a default level, which can be overridden with an environment variable
+* `set_logging_level` - sets the logging level of a `logging.Logger` instance
+* `str_to_logging_level` - turns a string logging level into a `logging` module one, used by `init_logging` and `set_logging_level`
+* `add_logging_level` - adds an option for the logging level to an `argparse.ArgumentParser` instance
+* `add_logger_name` - adds an option for a custom name for a logger to an `argparse.ArgumentParser` instance
+
+
+Changelog
+=========
+
+0.0.3 (2025-01-14)
+------------------
+
+- using underscore in project name now
+
+
+0.0.2 (2025-01-14)
+------------------
+
+- `init_logging` now supports specifying `stream` or `filename` or `handlers` as well as the `log_format`
+
+
+0.0.1 (2023-11-30)
+------------------
+
+- initial release
+

wai_logging-0.0.3/src/wai_logging.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+CHANGES.rst
+DESCRIPTION.rst
+LICENSE
+MANIFEST.in
+README.md
+setup.py
+src/wai/logging/__init__.py
+src/wai/logging/_argparse.py
+src/wai/logging/_core.py
+src/wai_logging.egg-info/PKG-INFO
+src/wai_logging.egg-info/SOURCES.txt
+src/wai_logging.egg-info/dependency_links.txt
+src/wai_logging.egg-info/top_level.txt

wai_logging-0.0.3/src/wai_logging.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

wai_logging-0.0.3/src/wai_logging.egg-info/top_level.txt

@@ -0,0 +1 @@
+wai