Merge pull request #17 from kjappelbaum/kjappelbaum/issue16

chore: make logger more customizable

Author: kjappelbaum

.flake8

@@ -20,26 +20,26 @@ jobs:
           pip freeze
       - name: Run pre-commit
         run: pre-commit run --all-files || ( git status --short ; git diff ; exit 1 )
-  docs:
-    name: Documentation
-    runs-on: ubuntu-latest
-    strategy:
-      matrix:
-        python-version: ["3.8"]
-    steps:
-      - uses: actions/checkout@v2
-      - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v2
-        with:
-          python-version: ${{ matrix.python-version }}
-      - name: Install dependencies
-        run: pip install tox
-      - name: Check RST conformity with doc8
-        run: tox -e doc8
-      - name: Check docstring coverage
-        run: tox -e docstr-coverage
-      - name: Check documentation build with Sphinx
-        run: tox -e docs
+  # docs:
+  #   name: Documentation
+  #   runs-on: ubuntu-latest
+  #   strategy:
+  #     matrix:
+  #       python-version: ["3.8"]
+  #   steps:
+  #     - uses: actions/checkout@v2
+  #     - name: Set up Python ${{ matrix.python-version }}
+  #       uses: actions/setup-python@v2
+  #       with:
+  #         python-version: ${{ matrix.python-version }}
+  #     - name: Install dependencies
+  #       run: pip install tox
+  #     - name: Check RST conformity with doc8
+  #       run: tox -e doc8
+  #     - name: Check docstring coverage
+  #       run: tox -e docstr-coverage
+  #     - name: Check documentation build with Sphinx
+  #       run: tox -e docs
   tests:
     name: Tests
     runs-on: ${{ matrix.os }}

.github/workflows/tests.yml

@@ -1,7 +1,6 @@
 API documentation
 =======================
 
-
 Analysis
 -------------
 .. automodule:: structuregraph_helpers.analysis
@@ -30,4 +29,42 @@ Subgraph
 Hash
 ------- -
 .. automodule:: structuregraph_helpers.hash
-    :members:
+    :members:
+
+
+
+Logging 
+---------
+
+structuregraph_helpers uses the `loguru <https://loguru.readthedocs.io/en/stable/index.html>`_  for logging. 
+By default, logging from structuregraph_helpers is disabled to not interfere with your logs.
+
+However, you can easily customize the logging:
+
+.. code-block:: python
+
+    import sys
+    from loguru import logger
+
+    # enable structuregraph_helpers logging 
+    logger.enable("structuregraph_helpers")
+    
+    # define the logging level
+    LEVEL = "INFO || DEBUG || WARNING || etc."
+
+    # set the handler
+    # for logging to stdout
+    logger.add(sys.stdout, level=LEVEL) 
+    # or for logging to a file
+    logger.add("my_log_file.log", level=LEVEL, enqueue=True) 
+
+
+In many cases, however, you might find it convenient to simply call :py:meth:`~structuregraph_helpers.utils.enable_logging`
+
+.. code-block:: python
+
+    from structuregraph_helpers.utils import enable_logging
+
+    enable_logging()
+
+which will enable logging with sane defaults (i.e. logging to ``stderr`` for ``INFO`` and ``WARNING`` levels).

docs/source/api.rst

@@ -133,3 +133,39 @@ exclude_lines =
 [darglint]
 docstring_style = google
 strictness = short
+
+#########################
+# Flake8 Configuration  #
+# (.flake8)             #
+#########################
+[flake8]
+ignore =
+    S101 # assert
+    S301 # pickle
+    S403 # pickle
+    S404
+    S603
+    W503 # Line break before binary operator (flake8 is wrong)
+    E203  # whitespace before ':'
+exclude =
+    .tox,
+    .git,
+    __pycache__,
+    docs/source/conf.py,
+    build,
+    dist,
+    tests/fixtures/*,
+    *.pyc,
+    *.egg-info,
+    .cache,
+    .eggs,
+    data
+    */_hasher.py
+max-line-length = 120
+max-complexity = 20
+import-order-style = pycharm
+application-import-names =
+    structuregraph_helpers
+    tests
+per-file-ignores =
+    tests/*.py:DAR101, D205, D100, DAR101, DAR201, D209, D103

setup.cfg

@@ -1,3 +1,5 @@
 # -*- coding: utf-8 -*-
-
 """Utilities for working with structure graphs."""
+from loguru import logger
+
+logger.disable("structuregraph_helpers")

src/structuregraph_helpers/__init__.py

@@ -1,6 +1,33 @@
 import json
+import sys
+from typing import List
+
+from loguru import logger
 
 
 def dump_json(data, filename):
     with open(filename, "w") as f:
         json.dump(data, f)
+
+
+def enable_logging() -> List[int]:
+    """Set up the structuregraph_helpers logging with sane defaults."""
+    logger.enable("structuregraph_helpers")
+
+    config = dict(
+        handlers=[
+            dict(
+                sink=sys.stderr,
+                format="<green>{time:YYYY-MM-DD HH:mm:ss.SSS Z UTC}</>"
+                " <red>|</> <lvl>{level}</> <red>|</> <cyan>{name}:{function}:{line}</>"
+                " <red>|</> <lvl>{message}</>",
+                level="INFO",
+            ),
+            dict(
+                sink=sys.stderr,
+                format="<red>{time:YYYY-MM-DD HH:mm:ss.SSS Z UTC} | {level} | {name}:{function}:{line} | {message}</>",
+                level="WARNING",
+            ),
+        ]
+    )
+    return logger.configure(**config)