Version 0.2.0 - add logging.Handler and improve documentation

Author: simonrob

README.md

@@ -6,15 +6,21 @@ from pyoslog import os_log, OS_LOG_DEFAULT
 os_log(OS_LOG_DEFAULT, 'Hello from Python!')
 ```
 
+
 ## Installation
-`python -m pip install pyoslog`
+```shell
+python -m pip install pyoslog
+```
+
+Pyoslog requires macOS 10.12 or later.
 
 
 ## Usage
-Pyoslog currently provides the methods [`os_log_create`](https://developer.apple.com/documentation/os/1643744-os_log_create), [`os_log_wih_type`](https://developer.apple.com/documentation/os/os_log_with_type) and [`os_log`](https://developer.apple.com/documentation/os/os_log) with the same signatures as their native versions.
+Pyoslog currently provides the methods [`os_log_create`](https://developer.apple.com/documentation/os/1643744-os_log_create), [`os_log_with_type`](https://developer.apple.com/documentation/os/os_log_with_type) and [`os_log`](https://developer.apple.com/documentation/os/os_log), each with the same signatures as their native versions.
 
-The module also offers a helper method, `log` that by default posts a message of type `OS_LOG_TYPE_DEFAULT` to `OS_LOG_DEFAULT`. For example, the shortcut `pyoslog.log('message')` is equivalent to `pyoslog.os_log_with_type(pyoslog.OS_LOG_DEFAULT, pyoslog.OS_LOG_TYPE_DEFAULT, 'message')`.
+The module also offers a helper method – `log` – that by default posts a message of type `OS_LOG_TYPE_DEFAULT` to `OS_LOG_DEFAULT`. For example, the shortcut `log('message')` is equivalent to `os_log_with_type(OS_LOG_DEFAULT, OS_LOG_TYPE_DEFAULT, 'message')`.
 
+The `Handler` class is designed for use with Python's inbuilt [logging](https://docs.python.org/3/library/logging.html) module.
 
 ### Labelling subsystem and category
 Create a log object using `os_log_create` and pass it to any of the log methods to add your own subsystem and category labels:
@@ -25,15 +31,46 @@ log = pyoslog.os_log_create('ac.robinson.pyoslog', 'custom-category')
 pyoslog.os_log_with_type(log, pyoslog.OS_LOG_TYPE_DEBUG, 'Message to log object', log, 'of type', pyoslog.OS_LOG_TYPE_DEBUG)
 ```
 
+
+### Integration with the logging module
+Use the pyoslog `Handler` to direct messages to pyoslog:
+
+```python
+import logging, pyoslog
+logger = logging.getLogger('My app name')
+logger.setLevel(logging.DEBUG)
+handler = pyoslog.Handler()
+handler.setSubsystem('org.example.your-app', 'filter-category')
+logger.addHandler(handler)
+logger.debug('message')
+```
+
+
 ### Receiving log messages
 Logs can be viewed using Console.app or the `log` command. For example, messages sent using the default configuration can be monitored using:
 
-`log stream --predicate 'processImagePath CONTAINS "Python"'`
+```shell
+log stream --predicate 'processImagePath CONTAINS "Python"'
+```
+
+Messages sent using custom configurations can be filtered more precisely. For example, to receive messages from the labelled subsystem used in the example above:
+
+```shell
+log stream --predicate 'subsystem == "ac.robinson.pyoslog"' --level=debug
+```
+
+See `man log` for further details about the available options and filters.
+
+
+## Alternatives
+At the time this module was created there were no alternatives available on [PyPi](https://pypi.org/). There are, however, other options available if this is not seen as a constraint:
 
-Messages sent using custom configurations can be filtered more precisely. For example, to receive messages from the labelled subsystem example above:
+- [apple_os_log_py](https://github.com/cedar101/apple_os_log_py)
+- [pymacoslog](https://github.com/douglas-carmichael/pymacoslog)
+- [loggy](https://github.com/pointy-tools/loggy)
 
-`log stream --predicate 'subsystem == "ac.robinson.pyoslog"' --level=debug`
+Note that the [pyobjc](https://pyobjc.readthedocs.io/) module [OSLog](https://pypi.org/project/pyobjc-framework-OSLog/) is for _reading_ from the unified logging system rather than writing to it. A `log.h` binding is on that project's [roadmap](https://github.com/ronaldoussoren/pyobjc/issues/377), but not yet implemented. 
 
 
 ## License
-[Apache 2.0](LICENSE)
+[Apache 2.0](LICENSE)

pyoslog/__init__.py

@@ -1,31 +1,3 @@
 """"Send messages to the macOS unified logging system. See: https://developer.apple.com/documentation/os/os_log"""
-import _pyoslog
-
-OS_LOG_DEFAULT = _pyoslog.OS_LOG_DEFAULT
-
-OS_LOG_TYPE_DEFAULT = _pyoslog.OS_LOG_TYPE_DEFAULT
-OS_LOG_TYPE_INFO = _pyoslog.OS_LOG_TYPE_INFO
-OS_LOG_TYPE_DEBUG = _pyoslog.OS_LOG_TYPE_DEBUG
-OS_LOG_TYPE_ERROR = _pyoslog.OS_LOG_TYPE_ERROR
-OS_LOG_TYPE_FAULT = _pyoslog.OS_LOG_TYPE_FAULT
-
-
-def os_log_create(subsystem, category):
-    """Creates a custom log object. See: https://developer.apple.com/documentation/os/1643744-os_log_create"""
-    return _pyoslog.os_log_create(subsystem, category)
-
-
-def os_log_with_type(log_object, log_type, *message):
-    """Sends a message at a specific logging level, such as default, info, debug, error, or fault, to the logging
-    system. See: https://developer.apple.com/documentation/os/os_log_with_type """
-    return _pyoslog.os_log_with_type(log_object, log_type, ' '.join(map(str, message)))
-
-
-def os_log(log_object, *message):
-    """Sends a default-level message to the logging system. See: https://developer.apple.com/documentation/os/os_log"""
-    return os_log_with_type(log_object, OS_LOG_TYPE_DEFAULT, *message)
-
-
-def log(*message, log_object=OS_LOG_DEFAULT, log_type=OS_LOG_TYPE_DEFAULT):
-    """Equivalent to os_log_with_type(log_object, log_type, *message) with the default log object and type"""
-    return os_log_with_type(log_object, log_type, *message)
+from .core import *
+from .handler import *

pyoslog/__version__.py

@@ -1,5 +1,5 @@
 __title__ = 'pyoslog'
-__version__ = '0.1.0'
+__version__ = '0.2.0'
 __description__ = 'Send messages to the macOS unified logging system'
 __author__ = 'Simon Robinson'
 __author_email__ = 'simon@robinson.ac'

pyoslog/core.py

@@ -0,0 +1,30 @@
+import _pyoslog
+
+OS_LOG_DEFAULT = _pyoslog.OS_LOG_DEFAULT
+
+OS_LOG_TYPE_DEFAULT = _pyoslog.OS_LOG_TYPE_DEFAULT
+OS_LOG_TYPE_INFO = _pyoslog.OS_LOG_TYPE_INFO
+OS_LOG_TYPE_DEBUG = _pyoslog.OS_LOG_TYPE_DEBUG
+OS_LOG_TYPE_ERROR = _pyoslog.OS_LOG_TYPE_ERROR
+OS_LOG_TYPE_FAULT = _pyoslog.OS_LOG_TYPE_FAULT
+
+
+def os_log_create(subsystem, category):
+    """Creates a custom log object. See: https://developer.apple.com/documentation/os/1643744-os_log_create"""
+    return _pyoslog.os_log_create(subsystem, category)
+
+
+def os_log_with_type(log_object, log_type, *message):
+    """Sends a message at a specific logging level, such as default, info, debug, error, or fault, to the logging
+    system. See: https://developer.apple.com/documentation/os/os_log_with_type """
+    return _pyoslog.os_log_with_type(log_object, log_type, ' '.join(map(str, message)))
+
+
+def os_log(log_object, *message):
+    """Sends a default-level message to the logging system. See: https://developer.apple.com/documentation/os/os_log"""
+    return os_log_with_type(log_object, OS_LOG_TYPE_DEFAULT, *message)
+
+
+def log(*message, log_object=OS_LOG_DEFAULT, log_type=OS_LOG_TYPE_DEFAULT):
+    """Equivalent to os_log_with_type(log_object, log_type, *message) with the default log object and type"""
+    return os_log_with_type(log_object, log_type, *message)

pyoslog/handler.py

@@ -0,0 +1,36 @@
+from .core import *
+import logging
+
+
+class Handler(logging.Handler):
+    """This logging Handler simply forwards all messages to pyoslog"""
+
+    def __init__(self):
+        """Initialise a Handler instance, logging to OS_LOG_DEFAULT at OS_LOG_TYPE_DEFAULT"""
+        logging.Handler.__init__(self)
+
+        self.log_object = OS_LOG_DEFAULT
+        self.log_type = OS_LOG_TYPE_DEFAULT
+
+        self._levelToType = {
+            logging.CRITICAL: OS_LOG_TYPE_FAULT,
+            logging.ERROR: OS_LOG_TYPE_ERROR,
+            logging.WARNING: OS_LOG_TYPE_DEFAULT,
+            logging.INFO: OS_LOG_TYPE_INFO,
+            logging.DEBUG: OS_LOG_TYPE_DEBUG,
+            logging.NOTSET: OS_LOG_TYPE_DEFAULT
+        }
+
+    def setLevel(self, level):
+        """Sets the log level, mapping logging.<level> to pyoslog.OS_LOG_TYPE_<equivalent level>"""
+        self.log_type = self._levelToType.get(level)
+        super().setLevel(level)
+
+    # noinspection PyPep8Naming
+    def setSubsystem(self, subsystem, category='default'):
+        """Sets the subsystem (in reverse DNS notation), and optionally a category to allow further filtering"""
+        self.log_object = os_log_create(subsystem, category)
+
+    def emit(self, record):
+        """Emit a record, sending its contents to pyoslog"""
+        os_log_with_type(self.log_object, self.log_type, self.format(record))

setup.py

@@ -23,6 +23,7 @@
     url=about['__url__'],
 
     platforms=['darwin'],
+    packages=[NAME],
     ext_modules=[Extension('_' + NAME, ['%s/_%s.c' % (NAME, NAME)])],
 
     package_data={'': ['LICENSE']},