Version 1.0.0: first stable release

Author: simonrob

README.md

@@ -106,21 +106,29 @@ When labelling subsystem and category using the native C methods there is a requ
 The pyoslog module handles this for you – there is no need to `del` or release these objects.
 
 
+## Limitations
+As noted above, while the macOS `os_log` API allows use of a format string with many methods, this name is required to be a C string literal.
+As a result, pyoslog hardcodes all format strings to `"%{public}s"`.
+
+
 ## Testing
-The pyoslog module's tests require the [pyobjc OSLog framework wrappers](https://pypi.org/project/pyobjc-framework-OSLog/) in order to verify output and, as a result, can only be run on macOS 10.15 or later.
+The pyoslog module's tests require the [pyobjc OSLog framework wrappers](https://pypi.org/project/pyobjc-framework-OSLog/) and the [storeWithScope initialiser](https://developer.apple.com/documentation/oslog/oslogstore/3548057-storewithscope) in order to verify output so, as a result, can only be run on macOS 12 or later.
+
 After installing the OSLog wrappers (via `python -m pip install pyobjc-framework-OSLog`), navigate to the [tests](https://github.com/simonrob/pyoslog/tree/main/tests) directory and run:
 
 ```shell
 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#L84) for discussion about why this is the case.
+See [`test_logging.py`](https://github.com/simonrob/pyoslog/blob/main/tests/test_logging.py#L93) for discussion about why this is the case.
 
 
 ## Alternatives
 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).
-Since then, the [macos-oslog](https://pypi.org/project/macos-oslog/) module has been released, with broadly equivalent functionality to pyoslog.
+Since then, the [macos-oslog](https://pypi.org/project/macos-oslog/) module has been released, with broadly equivalent functionality to pyoslog, except for the need to manually release the log object.
+There is also [os-signpost](https://pypi.org/project/os-signpost/), which uses `cython` to provide the [`OSSignposter`](https://developer.apple.com/documentation/os/ossignposter) API, and could easily be extended to provide `os_log` functionality.
+
 In addition, there are other options available if PyPi access is not seen as a constraint:
 
 - [apple_os_log_py](https://github.com/cedar101/apple_os_log_py)

build.sh

@@ -1,38 +1,50 @@
+# 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
+  echo 'Warning: not running in a Python virtual environment. Please either activate a venv or edit the script to confirm this action'
+  exit 1
+fi
+
 module=${PWD##*/} # get module name - relies on directory name == module name
 module=${module:-/}
 
-echo "Preparing environment for $module"
-python -m pip install twine # we don't have a requirements.txt so easiest just to be sure twine exists every time
+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
 
+python -m pip install --quiet --force-reinstall . # install pyoslog itself
+
 printf '\nType checking %s…\n' "$module"
-mypy pyoslog
+python -m mypy pyoslog
 
 printf '\nRunning tests for %s…\n' "$module"
-(cd tests && python -m unittest) # we don't fail on failed tests because they need a macOS version above our minimum
+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
 
 printf '\nBuilding documentation for %s…\n' "$module"
-python -m pip install -r docs/requirements.txt
+python -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…\n' "$module"
-python setup.py 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 setup.py -q clean --all sdist bdist_wheel --universal
 
 printf '\nValidating %s packages…\n' "$module"
-twine check dist/*
+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\n'
-  exit 1
+  printf '\nExiting build script - run "./build.sh deploy" to also upload to PyPi / Read the Docs (please git commit first)\n\n'
+  exit 0
 fi
 
 printf "\nUpload the $(tput bold)%s$(tput sgr0) package to the \033[0;32m$(tput bold)Test PyPI repository$(tput sgr0)\033[0m via Twine? (y to confirm; n to skip; any other key to exit): " "$module"
 read -r answer
 
 if [ "$answer" != "${answer#[Yy]}" ]; then
   PYPI_TEST_TOKEN=$(<versions/pypi-test.token)
-  if twine upload -u __token__ -p "$PYPI_TEST_TOKEN" --repository testpypi dist/*; then
+  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"
   else
     echo "Error uploading $module; exiting"
@@ -50,7 +62,7 @@ read -r answer
 
 if [ "$answer" != "${answer#[Yy]}" ]; then
   PYPI_DEPLOY_TOKEN=$(<versions/pypi-deploy.token)
-  if twine upload -u __token__ -p "$PYPI_DEPLOY_TOKEN" dist/*; then
+  if python -m twine upload -u __token__ -p "$PYPI_DEPLOY_TOKEN" dist/*; then
     echo "Upload of $module completed – view at https://pypi.org/project/$module"
 
     READTHEDOCS_TOKEN=$(<versions/readthedocs.token)

docs/conf.py

@@ -7,6 +7,8 @@
 import os
 import sys
 
+from recommonmark.parser import CommonMarkParser
+
 # Make sure pyoslog's source files are detected
 sys.path.insert(0, os.path.abspath('..'))
 
@@ -29,6 +31,12 @@
             lines.append(line.rstrip())
     output_file.write('\n'.join(lines))
 
+
+class CustomCommonMarkParser(CommonMarkParser):
+    def visit_document(self, node):
+        pass
+
+
 # -- Project information -----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
@@ -42,17 +50,22 @@
 
 print('Documenting', project, version)
 
+
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
+def setup(app):
+    # note include recommonmark this way to work around https://github.com/readthedocs/recommonmark/issues/177
+    app.add_source_suffix('.md', 'markdown')
+    app.add_source_parser(CustomCommonMarkParser)
+
+
 extensions = [
     'sphinx.ext.autodoc',
     'sphinx.ext.viewcode',
     'sphinx_toolbox.sidebar_links',
-    'sphinx_toolbox.github',
-    'recommonmark'  # note: https://github.com/readthedocs/recommonmark/issues/177
+    'sphinx_toolbox.github'
 ]
-source_suffix = ['.rst', '.md']
 
 autodoc_member_order = 'bysource'  # note: doesn't work with inherited members: github.com/sphinx-doc/sphinx/issues/628
 autodoc_preserve_defaults = True  # better display of log() defaults

pyoslog/__version__.py

@@ -1,6 +1,6 @@
 __title__ = 'pyoslog'
-__version__ = '0.6.0'
-__description__ = 'Send messages to the macOS unified logging system'
+__version__ = '1.0.0'
+__description__ = 'Send messages to the macOS unified logging system (os_log)'
 __author__ = 'Simon Robinson'
 __author_email__ = '[email protected]'
 __url__ = 'https://github.com/simonrob/pyoslog'

pyoslog/compatibility.py

@@ -7,9 +7,9 @@ def is_supported() -> bool:
     """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."""
-    if os.environ.get('PYOSLOG_OVERRIDE_IS_SUPPORTED', None):
+    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)')
         return True
-
-    return sys.platform == 'darwin' and sys.version_info >= (3, 0,) and float(
-        '.'.join(platform.mac_ver()[0].split('.')[:2])) >= 10.12
+    return supported

setup.py

@@ -48,6 +48,9 @@
         '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,
@@ -57,10 +60,14 @@
 
     license=about['__license__'],
     classifiers=[
-        'Development Status :: 4 - Beta',
         'Operating System :: MacOS',
+        'Programming Language :: Python',
+        'Programming Language :: C',
+        'Topic :: Software Development',
+        'Topic :: System :: Logging',
+        'Typing :: Typed',
         'Intended Audience :: Developers',
-        'License :: OSI Approved :: Apache Software License',
-        'Programming Language :: Python'
+        'Development Status :: 5 - Production/Stable',
+        'License :: OSI Approved :: Apache Software License'
     ]
 )

tests/test_handler.py

@@ -11,17 +11,23 @@
 
 print('Testing pyoslog', pkg_resources.get_distribution('pyoslog').version, 'handler')
 
-try:
-    import OSLog
-except ImportError:
-    if pyoslog.is_supported() and float('.'.join(platform.mac_ver()[0].split('.')[:2])) >= 10.15:
-        sys.exit('Error: cannot import pyobjc\'s OSLog; unable to run tests (do `pip install pyobjc-framework-OSLog`)')
-    else:
-        sys.exit('Error: pyobjc\'s OSLog is not supported on this platform (needs macOS 10.15+); unable to test output')
-
 
 class TestHandler(unittest.TestCase):
     def setUp(self):
+        try:
+            import OSLog
+        except ImportError:
+            if pyoslog.is_supported() and float('.'.join(platform.mac_ver()[0].split('.')[:2])) >= 10.15:
+                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'
+                print(skip_reason)
+                raise unittest.SkipTest(skip_reason)
+
         self.handler = pyoslog.Handler()
         self.assertEqual(self.handler._log_object, pyoslog.OS_LOG_DEFAULT)
         self.assertEqual(self.handler._log_type, pyoslog.OS_LOG_TYPE_DEFAULT)
@@ -47,8 +53,8 @@ def test_setSubsystem(self):
         # far more thorough testing is in test_setup.py (setSubsystem essentially duplicates os_log_create)
         self.handler.setSubsystem(pyoslog_test_globals.LOG_SUBSYSTEM, pyoslog_test_globals.LOG_CATEGORY)
         self.assertIsInstance(self.handler._log_object, pyoslog_core.os_log_t)
-        self.assertEqual(str(self.handler._log_object), 'os_log_t(%s:%s)' % (pyoslog_test_globals.LOG_SUBSYSTEM,
-                                                                             pyoslog_test_globals.LOG_CATEGORY))
+        self.assertEqual(str(self.handler._log_object), '<os_log_t (%s:%s)>' % (pyoslog_test_globals.LOG_SUBSYSTEM,
+                                                                                pyoslog_test_globals.LOG_CATEGORY))
 
     def test_emit(self):
         # far more thorough testing is in test_logging.py (emit essentially duplicates os_log_with_type)

tests/test_logging.py

@@ -10,21 +10,27 @@
 
 print('Testing pyoslog', pkg_resources.get_distribution('pyoslog').version, 'logging')
 
-try:
-    import OSLog
-except ImportError:
-    if pyoslog.is_supported() and float('.'.join(platform.mac_ver()[0].split('.')[:2])) >= 10.15:
-        sys.exit('Error: cannot import pyobjc\'s OSLog; unable to run tests (do `pip install pyobjc-framework-OSLog`)')
-    else:
-        sys.exit('Error: pyobjc\'s OSLog is not supported on this platform (needs macOS 10.15+); unable to test output')
-
 
 class TestLogging(unittest.TestCase):
     def setUp(self):
+        try:
+            import OSLog
+        except ImportError:
+            if pyoslog.is_supported() and float('.'.join(platform.mac_ver()[0].split('.')[:2])) >= 10.15:
+                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'
+                print(skip_reason)
+                raise unittest.SkipTest(skip_reason)
+
         self.log = pyoslog.os_log_create(pyoslog_test_globals.LOG_SUBSYSTEM, pyoslog_test_globals.LOG_CATEGORY)
         self.assertIsInstance(self.log, pyoslog_core.os_log_t)
-        self.assertEqual(str(self.log), 'os_log_t(%s:%s)' % (pyoslog_test_globals.LOG_SUBSYSTEM,
-                                                             pyoslog_test_globals.LOG_CATEGORY))
+        self.assertEqual(str(self.log), '<os_log_t (%s:%s)>' % (pyoslog_test_globals.LOG_SUBSYSTEM,
+                                                                pyoslog_test_globals.LOG_CATEGORY))
 
         # noinspection PyUnresolvedReferences
         log_scope = OSLog.OSLogStoreScope(OSLog.OSLogStoreCurrentProcessIdentifier)

tests/test_setup.py

@@ -14,10 +14,10 @@
 class TestSetup(unittest.TestCase):
     def test_constants(self):
         self.assertIsInstance(pyoslog.OS_LOG_DEFAULT, pyoslog_core.os_log_t)
-        self.assertEqual(str(pyoslog.OS_LOG_DEFAULT), 'os_log_t(OS_LOG_DEFAULT)')
+        self.assertEqual(str(pyoslog.OS_LOG_DEFAULT), '<os_log_t (OS_LOG_DEFAULT)>')
 
         self.assertIsInstance(pyoslog.OS_LOG_DISABLED, pyoslog_core.os_log_t)
-        self.assertEqual(str(pyoslog.OS_LOG_DISABLED), 'os_log_t(OS_LOG_DISABLED)')
+        self.assertEqual(str(pyoslog.OS_LOG_DISABLED), '<os_log_t (OS_LOG_DISABLED)>')
 
         self.assertEqual(pyoslog.OS_LOG_TYPE_DEFAULT, pyoslog_test_globals.TestLogTypes.OS_LOG_TYPE_DEFAULT.value)
         self.assertEqual(pyoslog.OS_LOG_TYPE_INFO, pyoslog_test_globals.TestLogTypes.OS_LOG_TYPE_INFO.value)
@@ -34,8 +34,8 @@ def test_is_supported(self):
     def test_os_log_create(self):
         log = pyoslog.os_log_create(pyoslog_test_globals.LOG_SUBSYSTEM, pyoslog_test_globals.LOG_CATEGORY)
         self.assertIsInstance(log, pyoslog_core.os_log_t)
-        self.assertEqual(str(log), 'os_log_t(%s:%s)' % (pyoslog_test_globals.LOG_SUBSYSTEM,
-                                                        pyoslog_test_globals.LOG_CATEGORY))
+        self.assertEqual(str(log), '<os_log_t (%s:%s)>' % (pyoslog_test_globals.LOG_SUBSYSTEM,
+                                                           pyoslog_test_globals.LOG_CATEGORY))
 
         # PyArg_ParseTuple in _pyoslog.c handles type validation - just ensure a string is required and test boundaries
         self.assertRaises(TypeError, pyoslog.os_log_create, (None, None))