Bunch of tidying, including Python 2.7 compatibility

.github/workflows/python-package.yml

@@ -5,9 +5,17 @@ name: Python package
 
 on:
   push:
-    branches: [ "master", "dev", "gha" ]
+    branches:
+      - master
+      - dev
+      - gha
+      - tidying
   pull_request:
-    branches: [ "master", "dev", "gha" ]
+    branches:
+      - master
+      - dev
+      - gha
+      - tidying
 
 jobs:
   build:
@@ -41,3 +49,22 @@ jobs:
     - name: Test with pytest
       run: |
         pytest
+
+  build-py27:
+
+    runs-on: ubuntu-latest
+    container:
+      image: python:2.7-slim
+    steps:
+    - uses: actions/checkout@v4
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade "pip<21" setuptools mock
+    - name: Compile library modules
+      run: |
+        python -m compileall diagnosticism
+    - name: Test with unittest
+      run: |
+        python tests/run_unittest.py
+      env:
+        PYTHONPATH: ${{ github.workspace }}

CHANGES.md

@@ -1,5 +1,16 @@
 # **Diagnosticism.Python** Changes
 
+## 0.15.3 - 27th June 2026
+
+* added top-level `__all__` documenting the public API;
+* replaced top-level star-imports with explicit imports;
+* restoring broken Python 2.7 compatibility;
+* removed `tests` and `examples` from installable package;
+* fixed `_str2bool()` defect;
+* added `python_requires` for Python 2.7 and Python 3.8+;
+* general tidying;
+
+
 ## 0.15.2 - 27th August 2025
 
 * project boilerplate;

MANIFEST.in

@@ -0,0 +1,3 @@
+include LICENSE README.md CHANGES.md EXAMPLES.md TODO.md
+recursive-include examples *.py
+recursive-include tests *.py

README.md

@@ -16,6 +16,7 @@ Diagnosticism library, for Python
 
 - [Introduction](#introduction)
 - [Installation \& usage](#installation--usage)
+	- [Python version compatibility](#python-version-compatibility)
 - [Components](#components)
 	- [Classes](#classes)
 		- [`DOOMGram`](#doomgram)
@@ -77,6 +78,18 @@ d.log(sev.INFO, "hello")
 ```
 
 
+### Python version compatibility
+
+**Diagnosticism.Python** is intended to run on **Python 2.7** and **Python
+3.8+**. GitHub Actions exercises **Python 2.7** and **Python 3.8–3.13**.
+
+| Requirement | Applies to |
+| ----------- | ---------- |
+| Python **2.7** or **3.8+** | Core contingent reporting, logging, tracing, and severity APIs |
+| Python **3.9+** | `@tracefunc` and `@asynctracefunc` decorators |
+
+The public API surface is listed in `diagnosticism.__all__`.
+
 
 ## Components
 

__init__.py

@@ -1,2 +1,4 @@
-# This file present to ensure that unittest's discover operates recursively
+# This file present to ensure that unittest's discover operates recursively.
+#
+# It is not exported from the package.
 

build_dist.sh

@@ -1,4 +1,10 @@
-#!/bin/bash
+#! /bin/bash
 
-python3 setup.py sdist
+set -e
 
+cd "$(dirname "$0")"
+
+rm -rf build/ dist/ diagnosticism.egg-info/
+
+python3 -m build
+python3 -m twine check dist/*

build_dist_uv.sh

@@ -0,0 +1,15 @@
+#! /bin/bash
+
+set -e
+
+cd "$(dirname "$0")"
+
+if [ ! -d .venv ]; then
+    uv venv
+fi
+
+rm -rf build/ dist/ diagnosticism.egg-info/
+
+uv pip install build twine
+uv run python -m build
+uv run twine check dist/*

diagnosticism/__init__.py

@@ -9,13 +9,14 @@
 __license__     =   'BSD-3-Clause'
 __maintainer__  =   'Matt Wilson'
 __status__      =   'Beta'
-__version__     =   '0.15.2'
+__version__     =   '0.15.3'
 
 import sys
 
 from .contingent_reporting import (
     abort,
     report,
+    set_default_trailing_prompt,
 )
 from .doomgram import (
     DOOMGram,
@@ -28,8 +29,33 @@
     log,
     set_log_filter,
 )
-from .program_name import *
-from .severity import *
+from .program_name import (
+    get_program_name,
+    set_program_name,
+)
+from .severity import (
+    ALERT,
+    BENCHMARK,
+    CRITICAL,
+    DEBUG0,
+    DEBUG1,
+    DEBUG2,
+    DEBUG3,
+    DEBUG4,
+    DEBUG5,
+    FAIL,
+    FAILURE,
+    INFO,
+    INFORMATIONAL,
+    NOTICE,
+    TRACE,
+    UNSPECIFIED,
+    VIOLATION,
+    WARN,
+    WARNING,
+    parse_verbosity,
+    severity_to_string,
+)
 from .tracing import (
     dbg,
     dbgfl,
@@ -44,12 +70,68 @@
 )
 if sys.version_info[:2] >= (3, 9):
     from .tracing import (
-        tracefunc,
         asynctracefunc,
+        tracefunc,
     )
 
 from .warning import warn
 
 
+__all__ = [
+    '__version__',
+
+    'ALERT',
+    'BENCHMARK',
+    'CRITICAL',
+    'DEBUG0',
+    'DEBUG1',
+    'DEBUG2',
+    'DEBUG3',
+    'DEBUG4',
+    'DEBUG5',
+    'DOOMGram',
+    'DOOMScope',
+    'FAIL',
+    'FAILURE',
+    'INFO',
+    'INFORMATIONAL',
+    'NOTICE',
+    'TRACE',
+    'UNSPECIFIED',
+    'VIOLATION',
+    'WARN',
+    'WARNING',
+    'abort',
+    'dbg',
+    'dbgfl',
+    'enable_logging',
+    'enable_tracing',
+    'file',
+    'fileline',
+    'filelinefunc',
+    'func',
+    'get_program_name',
+    'is_logging_enabled',
+    'is_severity_logged',
+    'is_tracing_enabled',
+    'line',
+    'log',
+    'parse_verbosity',
+    'report',
+    'set_default_trailing_prompt',
+    'set_log_filter',
+    'set_program_name',
+    'severity_to_string',
+    'trace',
+    'warn',
+]
+
+if sys.version_info[:2] >= (3, 9):
+    __all__.extend([
+        'asynctracefunc',
+        'tracefunc',
+    ])
+
+
 # ############################## end of file ############################# #
 

diagnosticism/contingent_reporting.py

@@ -25,8 +25,12 @@ def _supports_ansi_sequences():
 
 _OS_IS_POSIX = _supports_ansi_sequences()
 
-STOCK_TRAILING_PROMPT = 'use --help for usage'
-"""The trailing prompt used when trailing_prompt=True is passed to abort() (and family) and no default trailing prompt has been set (via set_default_trailing_prompt())"""
+STOCK_TRAILING_PROMPT = "use --help for usage"
+"""
+The trailing prompt used when trailing_prompt=True is passed to abort() (and
+family) and no default trailing prompt has been set (via
+set_default_trailing_prompt()).
+"""
 
 _trailing_prompt = None
 
@@ -47,7 +51,8 @@ def set_default_trailing_prompt(prompt):
 
     Notes
     -----
-        This method is NOT threadsafe, so in a multithreaded context the set prompt and/or the return value may not be as expected
+    This method is NOT threadsafe, so in a multithreaded context the set
+    prompt and/or the return value may not be as expected.
     """
 
     global _trailing_prompt
@@ -176,7 +181,7 @@ def _do_report(
 
     def conrep(
         message,
-        **kwargs,
+        **kwargs
     ):
         """
         DEPRECATED: use `report()`.
@@ -196,15 +201,18 @@ def report(
     file=None,
 ):
     """
-    Emits the given message (and optional prefix) on the contingent report stream.
+    Emits the given message (and optional prefix) on the contingent report
+    stream.
 
     Parameters
     ----------
     message : str
-        The (main body of the) message to be displayed, which is optionally prefixed by program-name + ': '
+        The (main body of the) message to be displayed, which is optionally
+        prefixed by program-name + ': '
 
     show_program_name : bool, optional
-        Prevents the default prefixing of the message with program-name + ': ' if `False`. Default is `True`
+        Prevents the default prefixing of the message with program-name +
+        ': ' if `False`. Default is `True`
     """
 
     trailing_prompt = False
@@ -227,21 +235,30 @@ def abort(
     file=None,
 ):
     """
-    Emits the given message (and optional prefix and suffix) on the contingent report stream, and then terminates the process
+    Emits the given message (and optional prefix and suffix) on the
+    contingent report stream, and then terminates the process.
 
     Parameters
     ----------
     message : str
-        The (main body of the) message to be displayed, which is optionally prefixed by program-name + ': ' and optionally suffixed by '; ' + trailing-prompt
+        The (main body of the) message to be displayed, which is optionally
+        prefixed by program-name + ': ' and optionally suffixed by '; ' +
+        trailing-prompt
 
     do_exit : bool, optional
-        Prevents default behaviour of a call to `sys.exit(1)` (after printing the abort message) if `False`. Default is `True`
+        Prevents default behaviour of a call to `sys.exit(1)` (after
+        printing the abort message) if `False`. Default is `True`
 
     show_program_name : bool, optional
-        Prevents the default prefixing of the message with program-name + ': ' if `False`. Default is `True`
+        Prevents the default prefixing of the message with program-name +
+        ': ' if `False`. Default is `True`
 
     trailing_prompt : str, bool, optional
-        Affects the use of the trailing prompt as follows: if `False`, no trailing prompt is shown; if a (non-empty) string, that is used; if `None`, the default trailing prompt, if any, is used; if `True`, the default trailing prompt is used if specified, otherwise `STOCK_TRAILING_PROMPT` is used
+        Affects the use of the trailing prompt as follows: if `False`, no
+        trailing prompt is shown; if a (non-empty) string, that is used; if
+        `None`, the default trailing prompt, if any, is used; if `True`, the
+        default trailing prompt is used if specified, otherwise
+        `STOCK_TRAILING_PROMPT` is used
     """
 
     file = _get_cr_file_or_default(file)