Merge branch 'main' into document-dynamic-levels

# Conflicts:
#	adafruit_logging/__init__.py

Author: FoamyGuy

.github/workflows/build.yml

@@ -42,9 +42,9 @@ jobs:
       # (e.g. - apt-get: gettext, etc; pip: circuitpython-build-tools, requirements.txt; etc.)
       run: |
         source actions-ci/install.sh
-    - name: Pip install pylint, Sphinx, pre-commit
+    - name: Pip install Sphinx, pre-commit
       run: |
-        pip install --force-reinstall pylint Sphinx sphinx-rtd-theme pre-commit
+        pip install --force-reinstall Sphinx sphinx-rtd-theme pre-commit
     - name: Library version
       run: git describe --dirty --always --tags
     - name: Pre-commit hooks

.pre-commit-config.yaml

@@ -18,17 +18,25 @@ repos:
     -   id: end-of-file-fixer
     -   id: trailing-whitespace
 -   repo: https://github.com/pycqa/pylint
-    rev: pylint-2.7.1
+    rev: v2.11.1
     hooks:
     -   id: pylint
         name: pylint (library code)
         types: [python]
-        exclude: "^(docs/|examples/|setup.py$)"
--   repo: local
-    hooks:
-    -   id: pylint_examples
-        name: pylint (examples code)
+        args:
+          - --disable=consider-using-f-string
+        exclude: "^(docs/|examples/|tests/|setup.py$)"
+    -   id: pylint
+        name: pylint (example code)
         description: Run pylint rules on "examples/*.py" files
-        entry: /usr/bin/env bash -c
-        args: ['([[ ! -d "examples" ]] || for example in $(find . -path "./examples/*.py"); do pylint --disable=missing-docstring,invalid-name $example; done)']
-        language: system
+        types: [python]
+        files: "^examples/"
+        args:
+        - --disable=missing-docstring,invalid-name,consider-using-f-string,duplicate-code
+    -   id: pylint
+        name: pylint (test code)
+        description: Run pylint rules on "tests/*.py" files
+        types: [python]
+        files: "^tests/"
+        args:
+        - --disable=missing-docstring,consider-using-f-string,duplicate-code

.pylintrc

@@ -59,7 +59,7 @@ confidence=
 # no Warning level messages displayed, use"--disable=all --enable=classes
 # --disable=W"
 # disable=import-error,print-statement,parameter-unpacking,unpacking-in-except,old-raise-syntax,backtick,long-suffix,old-ne-operator,old-octal-literal,import-star-module-level,raw-checker-failed,bad-inline-option,locally-disabled,locally-enabled,file-ignored,suppressed-message,useless-suppression,deprecated-pragma,apply-builtin,basestring-builtin,buffer-builtin,cmp-builtin,coerce-builtin,execfile-builtin,file-builtin,long-builtin,raw_input-builtin,reduce-builtin,standarderror-builtin,unicode-builtin,xrange-builtin,coerce-method,delslice-method,getslice-method,setslice-method,no-absolute-import,old-division,dict-iter-method,dict-view-method,next-method-called,metaclass-assignment,indexing-exception,raising-string,reload-builtin,oct-method,hex-method,nonzero-method,cmp-method,input-builtin,round-builtin,intern-builtin,unichr-builtin,map-builtin-not-iterating,zip-builtin-not-iterating,range-builtin-not-iterating,filter-builtin-not-iterating,using-cmp-argument,eq-without-hash,div-method,idiv-method,rdiv-method,exception-message-attribute,invalid-str-codec,sys-max-int,bad-python3-import,deprecated-string-function,deprecated-str-translate-call
-disable=print-statement,parameter-unpacking,unpacking-in-except,old-raise-syntax,backtick,long-suffix,old-ne-operator,old-octal-literal,import-star-module-level,raw-checker-failed,bad-inline-option,locally-disabled,locally-enabled,file-ignored,suppressed-message,useless-suppression,deprecated-pragma,apply-builtin,basestring-builtin,buffer-builtin,cmp-builtin,coerce-builtin,execfile-builtin,file-builtin,long-builtin,raw_input-builtin,reduce-builtin,standarderror-builtin,unicode-builtin,xrange-builtin,coerce-method,delslice-method,getslice-method,setslice-method,no-absolute-import,old-division,dict-iter-method,dict-view-method,next-method-called,metaclass-assignment,indexing-exception,raising-string,reload-builtin,oct-method,hex-method,nonzero-method,cmp-method,input-builtin,round-builtin,intern-builtin,unichr-builtin,map-builtin-not-iterating,zip-builtin-not-iterating,range-builtin-not-iterating,filter-builtin-not-iterating,using-cmp-argument,eq-without-hash,div-method,idiv-method,rdiv-method,exception-message-attribute,invalid-str-codec,sys-max-int,bad-python3-import,deprecated-string-function,deprecated-str-translate-call,import-error,bad-continuation
+disable=print-statement,parameter-unpacking,unpacking-in-except,old-raise-syntax,backtick,long-suffix,old-ne-operator,old-octal-literal,import-star-module-level,raw-checker-failed,bad-inline-option,locally-disabled,locally-enabled,file-ignored,suppressed-message,useless-suppression,deprecated-pragma,apply-builtin,basestring-builtin,buffer-builtin,cmp-builtin,coerce-builtin,execfile-builtin,file-builtin,long-builtin,raw_input-builtin,reduce-builtin,standarderror-builtin,unicode-builtin,xrange-builtin,coerce-method,delslice-method,getslice-method,setslice-method,no-absolute-import,old-division,dict-iter-method,dict-view-method,next-method-called,metaclass-assignment,indexing-exception,raising-string,reload-builtin,oct-method,hex-method,nonzero-method,cmp-method,input-builtin,round-builtin,intern-builtin,unichr-builtin,map-builtin-not-iterating,zip-builtin-not-iterating,range-builtin-not-iterating,filter-builtin-not-iterating,using-cmp-argument,eq-without-hash,div-method,idiv-method,rdiv-method,exception-message-attribute,invalid-str-codec,sys-max-int,bad-python3-import,deprecated-string-function,deprecated-str-translate-call,import-error,bad-continuation,unspecified-encoding
 
 # Enable the message, report, category or checker with the given id(s). You can
 # either give multiple identifier separated by comma (,) or put this option
@@ -256,7 +256,7 @@ ignore-docstrings=yes
 ignore-imports=yes
 
 # Minimum lines number of a similarity.
-min-similarity-lines=12
+min-similarity-lines=4
 
 
 [BASIC]

.readthedocs.yaml

@@ -0,0 +1,15 @@
+# SPDX-FileCopyrightText: 2021 ladyada for Adafruit Industries
+#
+# SPDX-License-Identifier: Unlicense
+
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+python:
+  version: "3.7"
+  install:
+    - requirements: docs/requirements.txt
+    - requirements: requirements.txt

.readthedocs.yml

@@ -40,6 +40,11 @@ Usage Example
     logger.error('Error message')
 
 
+Documentation
+=============
+
+API documentation for this library can be found on `Read the Docs <https://circuitpython.readthedocs.io/projects/logging/en/latest/>`_.
+
 Contributing
 ============
 

README.rst

@@ -87,7 +87,7 @@
     globals()[__name] = __value
 
 
-def level_for(value):
+def level_for(value: int) -> str:
     """Convert a numeric level to the most appropriate name.
 
     :param int value: a numeric level
@@ -104,7 +104,7 @@ def level_for(value):
 class LoggingHandler:
     """Abstract logging message handler."""
 
-    def format(self, log_level, message):
+    def format(self, log_level: int, message: str) -> str:
         """Generate a timestamped message.
 
         :param int log_level: the logging level
@@ -113,7 +113,7 @@ def format(self, log_level, message):
         """
         return "{0}: {1} - {2}".format(time.monotonic(), level_for(log_level), message)
 
-    def emit(self, log_level, message):
+    def emit(self, log_level: int, message: str):
         """Send a message where it should go.
         Placeholder for subclass implementations.
         """
@@ -123,8 +123,8 @@ def emit(self, log_level, message):
 class PrintHandler(LoggingHandler):
     """Send logging messages to the console by using print."""
 
-    def emit(self, log_level, message):
-        """Send a message to teh console.
+    def emit(self, log_level: int, message: str):
+        """Send a message to the console.
 
         :param int log_level: the logging level
         :param str message: the message to log
@@ -136,12 +136,11 @@ def emit(self, log_level, message):
 # The level module-global variables get created when loaded
 # pylint:disable=undefined-variable
 
-logger_cache = dict()
+logger_cache = {}
 null_logger = None
 
-
 # pylint:disable=global-statement
-def getLogger(logger_name):
+def getLogger(logger_name: str) -> "Logger":
     """Create or retrieve a logger by name.
 
     :param str logger_name: The name of the `Logger` to create/retrieve. `None`
@@ -170,23 +169,23 @@ def __init__(self):
         self._level = NOTSET
         self._handler = PrintHandler()
 
-    def setLevel(self, log_level):
+    def setLevel(self, log_level: int):
         """Set the logging cutoff level.
 
         :param int log_level: the lowest level to output
 
         """
         self._level = log_level
 
-    def getEffectiveLevel(self):
+    def getEffectiveLevel(self) -> int:
         """Get the effective level for this logger.
 
         :return: the lowest level to output
 
         """
         return self._level
 
-    def addHandler(self, handler):
+    def addHandler(self, handler: LoggingHandler):
         """Sets the handler of this logger to the specified handler.
         *NOTE* this is slightly different from the CPython equivalent which adds
         the handler rather than replacing it.
@@ -196,7 +195,7 @@ def addHandler(self, handler):
         """
         self._handler = handler
 
-    def log(self, log_level, format_string, *args):
+    def log(self, log_level: int, format_string: str, *args):
         """Log a message.
 
         :param int log_level: the priority level at which to log
@@ -208,7 +207,7 @@ def log(self, log_level, format_string, *args):
         if log_level >= self._level:
             self._handler.emit(log_level, format_string % args)
 
-    def debug(self, format_string, *args):
+    def debug(self, format_string: str, *args):
         """Log a debug message.
 
         :param str format_string: the core message string with embedded
@@ -218,7 +217,7 @@ def debug(self, format_string, *args):
         """
         self.log(DEBUG, format_string, *args)
 
-    def info(self, format_string, *args):
+    def info(self, format_string: str, *args):
         """Log a info message.
 
         :param str format_string: the core message string with embedded
@@ -228,7 +227,7 @@ def info(self, format_string, *args):
         """
         self.log(INFO, format_string, *args)
 
-    def warning(self, format_string, *args):
+    def warning(self, format_string: str, *args):
         """Log a warning message.
 
         :param str format_string: the core message string with embedded
@@ -238,7 +237,7 @@ def warning(self, format_string, *args):
         """
         self.log(WARNING, format_string, *args)
 
-    def error(self, format_string, *args):
+    def error(self, format_string: str, *args):
         """Log a error message.
 
         :param str format_string: the core message string with embedded
@@ -248,7 +247,7 @@ def error(self, format_string, *args):
         """
         self.log(ERROR, format_string, *args)
 
-    def critical(self, format_string, *args):
+    def critical(self, format_string: str, *args):
         """Log a critical message.
 
         :param str format_string: the core message string with embedded
@@ -267,30 +266,30 @@ class NullLogger:
     def __init__(self):
         """Dummy implementation."""
 
-    def setLevel(self, log_level):
+    def setLevel(self, log_level: int):
         """Dummy implementation."""
 
-    def getEffectiveLevel(self):
+    def getEffectiveLevel(self) -> int:
         """Dummy implementation."""
         return NOTSET
 
-    def addHandler(self, handler):
+    def addHandler(self, handler: LoggingHandler):
         """Dummy implementation."""
 
-    def log(self, log_level, format_string, *args):
+    def log(self, log_level: int, format_string: str, *args):
         """Dummy implementation."""
 
-    def debug(self, format_string, *args):
+    def debug(self, format_string: str, *args):
         """Dummy implementation."""
 
-    def info(self, format_string, *args):
+    def info(self, format_string: str, *args):
         """Dummy implementation."""
 
-    def warning(self, format_string, *args):
+    def warning(self, format_string: str, *args):
         """Dummy implementation."""
 
-    def error(self, format_string, *args):
+    def error(self, format_string: str, *args):
         """Dummy implementation."""
 
-    def critical(self, format_string, *args):
+    def critical(self, format_string: str, *args):
         """Dummy implementation."""

adafruit_logging.py renamed to adafruit_logging/__init__.py

@@ -0,0 +1,51 @@
+# SPDX-FileCopyrightText: 2021 Alec Delaney for Adafruit Industries
+#
+# SPDX-License-Identifier: MIT
+
+"""
+`extensions`
+====================================================
+
+CircuitPython logging extension for logging to files
+
+* Author(s): Alec Delaney
+"""
+
+from . import LoggingHandler
+
+__version__ = "0.0.0-auto.0"
+__repo__ = "https://github.com/adafruit/Adafruit_CircuitPython_Logging.git"
+
+
+class FileHandler(LoggingHandler):
+    """File handler for working with log files off of the microcontroller (like
+    an SD card)
+
+    :param filepath: The filepath to the log file
+    :param mode: Whether to write ('w') or append ('a'); default is to append
+    """
+
+    def __init__(self, filepath: str, mode: str = "a"):
+        self.logfile = open(  # pylint: disable=consider-using-with
+            filepath, mode, encoding="utf-8"
+        )
+
+    def close(self):
+        """Closes the file"""
+        self.logfile.close()
+
+    def format(self, level: int, msg: str):
+        """Generate a string to log
+
+        :param level: The level of the message
+        :param msg: The message to format
+        """
+        return super().format(level, msg) + "\r\n"
+
+    def emit(self, level: int, msg: str):
+        """Generate the message and write it to the UART.
+
+        :param level: The level of the message
+        :param msg: The message to log
+        """
+        self.logfile.write(self.format(level, msg))

adafruit_logging/extensions.py

@@ -0,0 +1,5 @@
+# SPDX-FileCopyrightText: 2021 Kattni Rembor for Adafruit Industries
+#
+# SPDX-License-Identifier: Unlicense
+
+sphinx>=4.0.0

docs/requirements.txt

@@ -0,0 +1,30 @@
+# SPDX-FileCopyrightText: 2021 Alec Delaney
+# SPDX-License-Identifier: MIT
+
+import board
+import busio
+from digitalio import DigitalInOut
+import storage
+import adafruit_sdcard
+import adafruit_logging as logging
+from adafruit_logging.extensions import FileHandler
+
+# Get chip select pin depending on the board, this one is for the Feather M4 Express
+sd_cs = board.D10
+
+# Set up an SD card to write to
+spi = busio.SPI(board.SCK, board.MOSI, board.MISO)
+cs = DigitalInOut(sd_cs)
+sdcard = adafruit_sdcard.SDCard(spi, cs)
+vfs = storage.VfsFat(sdcard)
+storage.mount(vfs, "/sd")
+
+# Initialize log functionality
+log_filepath = "/sd/testlog.log"
+logger = logging.getLogger("testlog")
+file_handler = FileHandler(log_filepath)
+logger.addHandler(file_handler)
+logger.setLevel(logging.INFO)
+
+logger.info("Logger initialized!")
+logger.debug("You can even add debug statements to the log!")