Version 1.0.1: restore backward compatibility; full test coverage

Author: simonrob

README.md

@@ -120,8 +120,8 @@ After installing the OSLog wrappers (via `python -m pip install pyobjc-framework
 python -m unittest
 ```
 
-Please note that if Console.app is live-streaming messages, some tests may fail.
-See [`test_logging.py`](https://github.com/simonrob/pyoslog/blob/main/tests/test_logging.py#L93) for discussion about why this is the case.
+All of pyoslog's code is covered by tests, but please note that if Console.app is live-streaming messages, some tests may fail.
+See [`test_logging.py`](https://github.com/simonrob/pyoslog/blob/main/tests/test_logging.py#L96) for discussion about why this is the case.
 
 
 ## Alternatives

build.sh

@@ -1,3 +1,6 @@
+#!/bin/bash
+set -Eeuo pipefail
+
 # this build script is quite forceful about setup - make sure not to mess up the system python
 PYTHON_VENV=$(python -c "import sys; sys.stdout.write('1') if hasattr(sys, 'real_prefix') or sys.base_prefix != sys.prefix else sys.stdout.write('0')")
 if [ "$PYTHON_VENV" == 0 ]; then
@@ -8,34 +11,60 @@ fi
 module=${PWD##*/} # get module name - relies on directory name == module name
 module=${module:-/}
 
-printf "\nPreparing environment for %s…\n" "$module"
-python -m pip install --quiet --upgrade pip
-python -m pip install --quiet setuptools wheel twine mypy sphinx # we don't have a requirements.txt, so easiest just to be sure build dependencies exist every time
-rm -rf dist
 rm -rf build
+rm -rf dist
+
+# check and upload built files with whatever python binary is globally set; use custom pyenv pyoslog versions below for building
+python -m pip install --quiet --upgrade pip
+python -m pip install --quiet twine
+
+if [ "${1:-0}" == 'all' ]; then
+  versions=(36 37 38 39 310) # run as "./build.sh all" to build with all reasonable python versions
+else
+  versions=(default)
+fi
+for i in "${versions[@]}"; do
+  printf "\nBuilding %s with Python %s\n" "$module" "$i"
+  if [ "$i" == 'default' ]; then
+    python_binary='python'
+  else
+    python_binary="${PYENV_ROOT}/versions/pyoslog$i/bin/python"
+  fi
+
+  printf "\nPreparing environment for %s…\n" "$module"
+  $python_binary -m pip install --quiet --upgrade pip
+  $python_binary -m pip install --quiet setuptools wheel coverage mypy sphinx # we don't have a requirements.txt, so easiest just to be sure build dependencies exist every time
 
-python -m pip install --quiet --force-reinstall . # install pyoslog itself
+  $python_binary -m pip install --quiet --force-reinstall . # install pyoslog itself (for tests)
 
-printf '\nType checking %s…\n' "$module"
-python -m mypy pyoslog
+  printf '\nType checking %s…\n' "$module"
+  $python_binary -m mypy pyoslog
 
-printf '\nRunning tests for %s…\n' "$module"
-python -m pip install --quiet pyobjc-framework-OSLog # separated from other installations because it will fail on unsupported platforms
-(cd tests && python -m unittest)                     # we don't fail on failed tests because they need a macOS version above our minimum
+  # note: for 100% test coverage, building must take place on macOS 12 or later, and debug logging must be enabled for all log objects:
+  # > sudo log config --mode 'level:debug' --subsystem 'ac.robinson.pyoslog'
+  # > sudo log config --mode 'level:debug'
+  # (the system mode can be restored to default afterwards via: `sudo log config --mode 'level:default'`)
+  printf '\nRunning tests and checking coverage for %s…\n' "$module"
+  $python_binary -m pip install --quiet pyobjc-framework-OSLog # separated from other installations because it will fail on unsupported platforms
+  (cd tests && $python_binary -m coverage run -m unittest)     # note re: test output - we selectively skip tests where they need a macOS version above our minimum
+  set +e                                                       # in environments we can't test (e.g., no OSLog framework) we don't care if coverage fails
+  (cd tests && $python_binary -m coverage html --include '*/pyoslog/*' --omit '*test*')
+  set -e
 
-printf '\nBuilding documentation for %s…\n' "$module"
-python -m pip install --quiet -r docs/requirements.txt
-export SPHINXOPTS=-q
-(cd docs && make clean html)
+  printf '\nBuilding documentation for %s…\n' "$module"
+  $python_binary -m pip install --quiet -r docs/requirements.txt
+  export SPHINXOPTS=-q
+  (cd docs && make clean html)
 
-printf '\nBuilding source and wheel (universal) distributions for %s ("can'\''t clean" messages can be ignored)…\n' "$module"
-python setup.py -q clean --all sdist bdist_wheel --universal
+  printf '\nBuilding source and wheel (universal) distributions for %s ("can'\''t clean" messages can be ignored)…\n' "$module"
+  $python_binary setup.py -q clean --all sdist bdist_wheel --universal
+done
 
 printf '\nValidating %s packages…\n' "$module"
 python -m twine check dist/*
 
-if [ -z "$1" ]; then # exit unless a parameter is provided (we use 'deploy' but don't actually care what it is)
-  printf '\nExiting build script - run "./build.sh deploy" to also upload to PyPi / Read the Docs (please git commit first)\n\n'
+if [ "${1:-0}" != 'deploy' ]; then
+  printf '\nBuild complete - exiting script. Run "./build.sh deploy" to also upload to PyPi / Read the Docs (please git commit first)\n\n'
   exit 0
 fi
 
@@ -45,7 +74,7 @@ read -r answer
 if [ "$answer" != "${answer#[Yy]}" ]; then
   PYPI_TEST_TOKEN=$(<versions/pypi-test.token)
   if python -m twine upload -u __token__ -p "$PYPI_TEST_TOKEN" --repository testpypi dist/*; then
-    echo "Upload of $module completed – install via: python -m pip install --force-reinstall --index-url https://test.pypi.org/simple/ $module"
+    echo "Upload of $module completed – install via: python -m pip install --force-reinstall --index-url https://test.pypi.org/simple/ $module (forcing version via $module==X.X.X if needed)"
   else
     echo "Error uploading $module; exiting"
     exit 1
@@ -68,6 +97,7 @@ if [ "$answer" != "${answer#[Yy]}" ]; then
     READTHEDOCS_TOKEN=$(<versions/readthedocs.token)
     echo "Triggering a Read the Docs build for $module – view at https://$module.readthedocs.io"
     curl -X POST -H "Authorization: Token $READTHEDOCS_TOKEN" "https://readthedocs.org/api/v3/projects/$module/versions/latest/builds/"
+    echo ''
   else
     echo "Error: $module upload failed"
     exit 1

pyoslog/__version__.py

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

pyoslog/compatibility.py

@@ -3,13 +3,17 @@
 import sys
 
 
-def is_supported() -> bool:
+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."""
     supported = sys.platform == 'darwin' and sys.version_info >= (3, 0,) and float(
         '.'.join(platform.mac_ver()[0].split('.')[:2])) >= 10.12
-    if not supported and os.environ.get('PYOSLOG_OVERRIDE_IS_SUPPORTED', ''):
-        print('Warning: overriding is_supported() on an unsupported platform (use to build documentation only)')
+    if os.environ.get('PYOSLOG_OVERRIDE_IS_SUPPORTED', ''):
+        print('Warning: overriding pyoslog.is_supported() to return True in all cases - '
+              'use only to build documentation and/or run tests')
         return True
     return supported
+
+
+is_supported.__annotations__ = {'return': bool}

pyoslog/core.py

@@ -3,10 +3,10 @@
 
 try:
     import _pyoslog  # type: ignore
-except ImportError:
+except ImportError:  # pragma: no cover
     # noinspection PyPep8Naming
     class _pyoslog:  # type: ignore
-        print('Warning: mocking _pyoslog class on an unsupported platform (use to build documentation only)')
+        print('Warning: mocking _pyoslog class on an unsupported platform - use to build documentation only')
         OS_LOG_TYPE_DEFAULT = 0
         OS_LOG_TYPE_INFO = 0
         OS_LOG_TYPE_DEBUG = 0
@@ -40,11 +40,11 @@ def __repr__(self) -> str:
 OS_LOG_DISABLED = os_log_t(None, None, None)  # type: ignore
 OS_LOG_DISABLED._description = '<os_log_t (OS_LOG_DISABLED)>'
 
-OS_LOG_TYPE_DEFAULT: int = _pyoslog.OS_LOG_TYPE_DEFAULT
-OS_LOG_TYPE_INFO: int = _pyoslog.OS_LOG_TYPE_INFO
-OS_LOG_TYPE_DEBUG: int = _pyoslog.OS_LOG_TYPE_DEBUG
-OS_LOG_TYPE_ERROR: int = _pyoslog.OS_LOG_TYPE_ERROR
-OS_LOG_TYPE_FAULT: int = _pyoslog.OS_LOG_TYPE_FAULT
+OS_LOG_TYPE_DEFAULT = _pyoslog.OS_LOG_TYPE_DEFAULT  # type: int
+OS_LOG_TYPE_INFO = _pyoslog.OS_LOG_TYPE_INFO  # type: int
+OS_LOG_TYPE_DEBUG = _pyoslog.OS_LOG_TYPE_DEBUG  # type: int
+OS_LOG_TYPE_ERROR = _pyoslog.OS_LOG_TYPE_ERROR  # type: int
+OS_LOG_TYPE_FAULT = _pyoslog.OS_LOG_TYPE_FAULT  # type: int
 
 
 def os_log_create(subsystem: str, category: str) -> os_log_t:

setup.py

@@ -1,4 +1,5 @@
 import os
+import sys
 
 import setuptools
 
@@ -15,10 +16,13 @@
 # see compatibility.py - allow installation on older versions (or other OSs) but provide is_supported() at runtime
 compatibility_module_name = 'compatibility'
 compatibility_module_path = os.path.join(working_directory, '%s.py' % compatibility_module_name)
+is_old_python_version = sys.version_info < (3, 5,)
 try:
     # noinspection PyUnresolvedReferences
     import importlib.util
 
+    if is_old_python_version:  # importlib.util.module_from_spec wasn't always present
+        raise ImportError('importlib.util.module_from_spec is not available')
     spec = importlib.util.spec_from_file_location(compatibility_module_name, compatibility_module_path)
     compatibility = importlib.util.module_from_spec(spec)
     spec.loader.exec_module(compatibility)
@@ -48,13 +52,13 @@
         'Source Code': about['__url__'],
     },
 
-    # 3.6+ for core.py constants inline type hints, but not enabled because we support installation on earlier versions
-    # python_requires='>=3.6',
-
     platforms=['darwin'],
     packages=[NAME],
     ext_modules=ext_modules,
 
+    # could do, e.g., 'typing;python_version<"3.5"' but some old versions don't support that syntax...
+    install_requires=['typing'] if is_old_python_version else [],
+
     package_data={'': ['LICENSE']},
     include_package_data=True,
 

tests/test_handler.py

@@ -1,6 +1,5 @@
 import logging
 import platform
-import sys
 import unittest
 
 import pkg_resources
@@ -14,17 +13,20 @@
 
 class TestHandler(unittest.TestCase):
     def setUp(self):
+        tests_supported_macos = float('.'.join(platform.mac_ver()[0].split('.')[:2])) >= 12
         try:
             import OSLog
+            if not tests_supported_macos:
+                raise ImportError('unsupported macOS version for testing')
         except ImportError:
-            if pyoslog.is_supported() and float('.'.join(platform.mac_ver()[0].split('.')[:2])) >= 10.15:
+            if pyoslog.is_supported() and tests_supported_macos:
                 skip_reason = 'Warning: cannot import pyobjc\'s OSLog; unable to run tests (run `pip install ' \
                               'pyobjc-framework-OSLog`)'
                 print(skip_reason)
                 raise unittest.SkipTest(skip_reason)
             else:
-                skip_reason = 'Warning: pyobjc\'s OSLog is not supported on this platform (requires macOS 10.15+); ' \
-                              'unable to test logging Handler'
+                skip_reason = 'Warning: pyobjc\'s OSLog is not fully supported on this platform (requires macOS ' \
+                              '12+); unable to test logging Handler'
                 print(skip_reason)
                 raise unittest.SkipTest(skip_reason)
 

tests/test_logging.py

@@ -1,5 +1,4 @@
 import platform
-import sys
 import unittest
 
 import pkg_resources
@@ -13,17 +12,20 @@
 
 class TestLogging(unittest.TestCase):
     def setUp(self):
+        supported_macos = float('.'.join(platform.mac_ver()[0].split('.')[:2])) >= 12
         try:
             import OSLog
+            if not supported_macos:
+                raise ImportError('unsupported macOS version for testing')
         except ImportError:
-            if pyoslog.is_supported() and float('.'.join(platform.mac_ver()[0].split('.')[:2])) >= 10.15:
+            if pyoslog.is_supported() and supported_macos:
                 skip_reason = 'Warning: cannot import pyobjc\'s OSLog; unable to run tests (run `pip install ' \
                               'pyobjc-framework-OSLog`)'
                 print(skip_reason)
                 raise unittest.SkipTest(skip_reason)
             else:
-                skip_reason = 'Warning: pyobjc\'s OSLog is not supported on this platform (requires macOS 10.15+); ' \
-                              'unable to test os_log output'
+                skip_reason = 'Warning: pyobjc\'s OSLog is not fully supported on this platform (requires macOS ' \
+                              '12+); unable to test os_log output'
                 print(skip_reason)
                 raise unittest.SkipTest(skip_reason)
 
@@ -62,11 +64,15 @@ def test_os_log_type_enabled(self):
 
     def test_os_log_info_enabled(self):
         # note that os_log_info_enabled() just calls os_log_type_enabled - more thorough testing can be found there
-        self.test_os_log_type_enabled()
+        expected_value = pyoslog.os_log_type_enabled(pyoslog.OS_LOG_DEFAULT,
+                                                     pyoslog_test_globals.TestLogTypes.OS_LOG_TYPE_INFO.value)
+        self.assertEqual(pyoslog.os_log_info_enabled(pyoslog.OS_LOG_DEFAULT), expected_value)
 
     def test_os_log_debug_enabled(self):
         # note that os_log_debug_enabled() just calls os_log_type_enabled - more thorough testing can be found there
-        self.test_os_log_type_enabled()
+        expected_value = pyoslog.os_log_type_enabled(pyoslog.OS_LOG_DEFAULT,
+                                                     pyoslog_test_globals.TestLogTypes.OS_LOG_TYPE_DEBUG.value)
+        self.assertEqual(pyoslog.os_log_debug_enabled(pyoslog.OS_LOG_DEFAULT), expected_value)
 
     def test_os_log_with_type(self):
         # PyArg_ParseTuple in _pyoslog.c handles type validation - just ensure objects are required and test boundaries
@@ -90,7 +96,7 @@ def test_os_log_with_type(self):
             pyoslog.os_log_with_type(pyoslog.OS_LOG_DEFAULT, log_type.value, sent_message)
             received_message = pyoslog_test_globals.get_latest_log_message(self.log_store)
 
-            # only test types that are enabled - note that starting streaming in Console.app seems to enable all levels,
+            # only test types that are enabled - note: starting streaming in Console.app appears to enable all levels,
             # but actually starts "STREAM_LIVE" mode (see `sudo log config --status`) which makes os_log_type_enabled
             # return True for all levels, but doesn't let OSLog retrieve them - as a result, some tests will fail when
             # Console.app is live-streaming logs

tests/test_setup.py

@@ -1,3 +1,4 @@
+import os
 import platform
 import sys
 import unittest
@@ -29,7 +30,12 @@ def test_is_supported(self):
         # a little pointless since our platform check and that from is_supported() are identical, but no other option
         matching_platform = sys.platform == 'darwin' and sys.version_info >= (3, 0,) and float(
             '.'.join(platform.mac_ver()[0].split('.')[:2])) >= 10.12
-        self.assertEqual(matching_platform, pyoslog.is_supported())
+        self.assertEqual(pyoslog.is_supported(), matching_platform)
+
+        # a little contrived, but might as well test the documentation building special case
+        os.environ['PYOSLOG_OVERRIDE_IS_SUPPORTED'] = '1'
+        self.assertEqual(pyoslog.is_supported(), True)
+        del os.environ['PYOSLOG_OVERRIDE_IS_SUPPORTED']
 
     def test_os_log_create(self):
         log = pyoslog.os_log_create(pyoslog_test_globals.LOG_SUBSYSTEM, pyoslog_test_globals.LOG_CATEGORY)