Add is_supported() - install/import on incompatible macOS versions

Author: simonrob

README.md

@@ -1,5 +1,5 @@
 # Pyoslog
-Pyoslog is a simple extension to send messages to the macOS [unified logging system](https://developer.apple.com/documentation/os/os_log) from Python.
+Pyoslog is a simple Python module that allows you to send messages to the macOS [unified logging system](https://developer.apple.com/documentation/os/os_log).
 
 ```python
 from pyoslog import os_log, OS_LOG_DEFAULT
@@ -8,19 +8,26 @@ os_log(OS_LOG_DEFAULT, 'Hello from Python!')
 
 
 ## Installation
+Pyoslog requires macOS 10.12 or later.
+Install using `pip`:
+
 ```shell
 python -m pip install pyoslog
 ```
 
-Pyoslog requires macOS 10.12 or later.
+The module will install and import without error on earlier macOS versions.
+Use `pyoslog.is_supported()` if you need to support old macOS versions and want to know at runtime whether to use pyoslog.
+Please note that if `is_supported()` returns `False` then none of the module's other methods or constants will exist.
 
 
 ## Usage
 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 `log('message')` is equivalent to `os_log_with_type(OS_LOG_DEFAULT, 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.
+It works as a drop-in replacement for other Handler varieties.
 
 ### 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:
@@ -45,15 +52,20 @@ logger.addHandler(handler)
 logger.debug('message')
 ```
 
+To configure the Handler's output type, use `handler.setLevel` with a level from the logging module.
+These are mapped internally to the `OS_LOG_TYPE` values – for example, `handler.setLevel(logging.DEBUG)` will configure the Handler to output messages of type `OS_LOG_TYPE_DEBUG`.
+
 
 ### 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:
+Logs can be viewed using Console.app or the `log` command.
+For example, messages sent using the default configuration can be streamed using:
 
 ```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:
+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
@@ -62,14 +74,21 @@ log stream --predicate 'subsystem == "ac.robinson.pyoslog"' --level=debug
 See `man log` for further details about the available options and filters.
 
 
+### Handling cleanup
+When labelling subsystem and category using the native C methods there is a requirement to free the log object after use (using `os_release`).
+The pyoslog module handles this for you – there is no need to `del` or release these objects.
+
+
 ## 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:
+At the time this module was created there were no alternatives available on [PyPi](https://pypi.org/search/?q=macos+unified+logging&c=Operating+System+%3A%3A+MacOS).
+There are, however, other options available if this is not seen as a constraint:
 
 - [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)
 
-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. 
+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

pyoslog/__init__.py

@@ -1,3 +1,8 @@
 """"Send messages to the macOS unified logging system. See: https://developer.apple.com/documentation/os/os_log"""
-from .core import *
-from .handler import *
+from .compatibility import is_supported
+
+if is_supported():
+    from .core import *
+    from .handler import *
+
+del compatibility

pyoslog/__version__.py

@@ -1,5 +1,5 @@
 __title__ = 'pyoslog'
-__version__ = '0.2.0'
+__version__ = '0.3.0'
 __description__ = 'Send messages to the macOS unified logging system'
 __author__ = 'Simon Robinson'
 __author_email__ = '[email protected]'

pyoslog/compatibility.py

@@ -0,0 +1,9 @@
+import platform
+import sys
+
+
+def is_supported():
+    """Unified logging is only present in macOS 10.12 and later, but it is nicer to not have to check OS type or version
+    strings when installing or importing the module - use this method at runtime to check whether it is supported. It is
+    important to note that if is_supported() is False then none of the module's other methods/constants will exist."""
+    return sys.platform == 'darwin' and float('.'.join(platform.mac_ver()[0].split('.')[:2])) >= 10.12

pyoslog/core.py

@@ -16,7 +16,7 @@ def 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 """
+    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)))
 
 

setup.py

@@ -1,16 +1,27 @@
+import importlib.util
 import os
+
 from setuptools import setup, Extension
 
 NAME = 'pyoslog'
 
 about = {}
-working_directory = os.path.abspath(os.path.dirname(__file__))
-with open(os.path.join(working_directory, NAME, '__version__.py')) as version_file:
+working_directory = os.path.join(os.path.abspath(os.path.dirname(__file__)), NAME)
+with open(os.path.join(working_directory, '__version__.py')) as version_file:
     exec(version_file.read(), about)
 
 with open('README.md') as readme_file:
     readme = readme_file.read()
 
+# see compatibility.py - allow installation on older versions but provide is_supported() at runtime
+spec = importlib.util.spec_from_file_location('compatibility', os.path.join(working_directory, 'compatibility.py'))
+compatibility = importlib.util.module_from_spec(spec)
+spec.loader.exec_module(compatibility)
+ext_modules = []
+# noinspection PyUnresolvedReferences
+if compatibility.is_supported():
+    ext_modules.append(Extension('_' + NAME, ['%s/_%s.c' % (NAME, NAME)]))
+
 # https://setuptools.pypa.io/en/latest/references/keywords.html
 setup(
     name=NAME,
@@ -24,7 +35,7 @@
 
     platforms=['darwin'],
     packages=[NAME],
-    ext_modules=[Extension('_' + NAME, ['%s/_%s.c' % (NAME, NAME)])],
+    ext_modules=ext_modules,
 
     package_data={'': ['LICENSE']},
     include_package_data=True,