diagnosticism 0.16.0

Basic diagnostic facilities, for Python

Diagnosticism.Python

Diagnosticism, for Python

Table of Contents

• Introduction
• Installation & usage
  • Python version compatibility
• Components
  • Classes
    • DOOMGram
    • DOOMScope
  • Constants
    • Diagnostic Logging API
    • Contingent Reporting API
  • Context Managers
  • Decorators
    • asynctracefunc
    • tracefunc
  • Functions
    • Contingent Reporting API
    • Debugging API
    • Diagnostic Logging API
    • Tracing API
    • Time formatting API
• Examples
• Project Information
  • Where to get help
  • Contribution guidelines
  • Dependencies
    • Efferent (fan-out)
      • Development Dependencies
    • Afferent (fan-in)
  • Related projects
  • License

Introduction

Diagnosticism is a standalone library of simple components for aiding in diagnostics for Python projects. It contains versions of components seen in the other Diagnosticisms - see below - though there is not a 1-to-1 correspondence between any of them.

Installation & usage

Install via pip or pip3, as in:

$ pip3 install diagnosticism

Use via import:

import diagnosticism

When using the simple logging facilities, we find it convenient to import as follows:

import diagnosticism as d
import diagnosticism.severity as sev

that may then be used as:

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

Diagnosticism.Python provides components in the following categories:

• Contingent Reporting
• Diagnostic Logging
• Time formatting
• Tracing

NOTE: for the moment, the Diagnostic Logging facilities emit to the standard error stream, via the Contingent Reporting API. In the near future this will be changed to work with more sophisticated logging libraries, including the standard logging facilities and the (as yet to be release) Pantheios.Python.

Classes

The following classes are defined:

DOOMGram

DOOMGram - Decimal Order-Of-Magnitude frequency histoGRAM - is a class for recording order-of-magnitude of operation timings, and then rendering the results in a text-based histogram format, as in:

DOOMScope

DOOMScope is a context-manager for use with DOOMGram for measuring scoped chunks of logic.

The example program examples/doomgram.py illustrates these two types in combination

# examples/doomgram.py

def main():

    dg = DOOMGram()

    for _ in range(1_000):

        r = random.uniform(1, 1_000)

        d = r / 1_000_000

        with DOOMScope(dg):

            time.sleep(d)

    print("dg:", dg)

. . .

and produces output such as:

dg: ___abcc_____

which indicates the following breakdown of operation - in this case a random sleep() - timings:

Time period(s)	Number of events in that period
Nanoseconds	no records
Microseconds	1-9 in 1µs (a); 10-99 in 10µs (b); 100-899 in 100µs (c)
Milliseconds	100-999 in 1ms (c)
Seconds	no records

Constants

Diagnostic Logging API

The following constants are defined:

Constant	API	Purpose
STOCK_TRAILING_PROMPT	Contingent Reporting	The stock trailing prompt, which is defined as "use --help for usage".

Contingent Reporting API

The following constants are defined:

Constant	API	Purpose
VIOLATION	Diagnostic Logging	Severity level suitable for use when logging that a design violation has occurred.
ALERT	Diagnostic Logging	Severity level suitable for use when logging that a fatal program failure has occurred.
CRITICAL	Diagnostic Logging	Severity level suitable for use when logging that a critical failure has occurred.
FAILURE	Diagnostic Logging	Severity level suitable for use when logging that a failure has occurred.
WARNING	Diagnostic Logging	Severity level suitable for use when issuing a warning.
NOTICE	Diagnostic Logging	Severity level suitable for use when logging an important normative condition.
INFORMATIONAL	Diagnostic Logging	Severity level suitable for use when logging a normative condition.
DEBUG0	Diagnostic Logging	The highest debug severity level.
DEBUG1	Diagnostic Logging	The second highest debug severity level.
DEBUG2	Diagnostic Logging	The third highest debug severity level.
DEBUG3	Diagnostic Logging	The fourth highest debug severity level.
DEBUG4	Diagnostic Logging	The fifth highest debug severity level.
DEBUG5	Diagnostic Logging	The sixth highest debug severity level.
TRACE	Diagnostic Logging	Severity level suitable at which trace statements are issued.
BENCHMARK	Diagnostic Logging	Severity level suitable at which benchmark statements are issued.
DEBUG	Diagnostics Logging	Alias for DEBUG5
FAIL	Diagnostics Logging	Alias for FAILURE
WARN	Diagnostics Logging	Alias for WARNING
INFO	Diagnostics Logging	Alias for INFORMATIONAL

NOTE: all the severity level constants are for use with the log() function (as well as for setting/getting with set_log_filter() and is_severity_logged()).

Context Managers

The following context managers are defined:

• DOOMScope - see above;

Decorators

The following decorators are defined:

asynctracefunc

Decorate that provides the equivalent functionality as @tracefunc for async functions and methods.

tracefunc

Decorator to be applied to functions and methods to save the need to call d.trace(), for example rather than:

def start():
	d.trace()
	. . .

def submit_work(name, job, priority=-1):
	d.trace()
	. . .

you can, more cleanly, write:

@d.tracefunc
def start():
	. . .

@d.tracefunc
def submit_work(name, job, priority=-1):
	. . .

Functions

Contingent Reporting API

The following functions are defined:

Function	Purpose
abort()	Issues a contingent report (via conrep()) and then terminating the process.
report()	Issues a message string as a contingent report, by defaulting writing output to sys.stderr.
set_default_trailing_prompt()	Sets the default trailing prompt.
warn()	An analogue to Ruby's warn(), this issues the given message(s) to (by default0 the standard error stream and, if logging is enabled, also log()s at WARNING severity level.

Debugging API

Function	Purpose
file()	Obtains the file in which the calling function is defined.
fileline()	Obtains the file+line in which the calling function is defined.
filelinefunc()	Obtains the file+line+function in which the calling function is defined.
func()	Obtains the function in which the calling function is defined.
line()	Obtains the line on which the calling function is defined.

Diagnostic Logging API

Function	Purpose
enable_logging()	Enables/disables logging, whether from a constant or from a named environment variable.
is_logging_enabled()	Indicates whether logging is enabled.
is_severity_logged()	Indicates whether a log statement at a given severity will be logged.
log()	Submits a diagnostic log message at a given severity (which will be emitted in the case that is_logging_enabled(sev)) would return True).
set_log_filter()	Sets a logging filter - either a threshold severity, or a `dict`` mapping severity levels to enablement flags - that allows fine-grained control of which levels are emitted.

Tracing API

Function	Purpose
dbg()	Similar to Rust's dbg!() macro, can be passed any number of normal and keyword arguments and traces their name, type, and value.
dbgfl()	Like dbg(), but include fileline() information in the TRACE statement produced.
enable_tracing()	Enables/disables tracing, whether from a constant or from a named environment variable.
is_tracing_enabled()	Indicates whether tracing is enabled.
trace()	Traces the name and signature of the calling function, including the values of all its arguments.

Time formatting API

Function	Purpose
nanoseconds_to_string()	Formats a nanosecond count as a compact human-readable duration string, adapting the unit (ns, µs, ms, s) and decimal precision to keep roughly three significant digits in the numeric portion. Zero is always "0s". An optional format_spec may include '+' to cause positive values to include an explicit leading sign.

For example:

from diagnosticism import nanoseconds_to_string

nanoseconds_to_string(123_456_789)       # '123.4ms'
nanoseconds_to_string(      6_789)       # '6.789µs'
nanoseconds_to_string(999_772_000, '+')  # '+999.7ms'

Examples

Examples are provided in the examples directory, along with a markdown description for each. A detailed list TOC of them is provided in EXAMPLES.md.

Project Information

Where to get help

GitHub Page

Contribution guidelines

Defect reports, feature requests, and pull requests are welcome on https://github.com/synesissoftware/Diagnosticism.Python.

Dependencies

Diagnosticism.Python has no (non-development) runtime dependencies.

Efferent (fan-out)

Libraries upon which Diagnosticism.Python depends:

None.

Development Dependencies

• mock — required for running the unit-test suite on Python 2.7;

Afferent (fan-in)

Projects that depend on Diagnosticism.Python:

• asynkio;
• libpath.Python;

Related projects

• Diagnosticism (C);
• Diagnosticism.Go;
• Diagnosticism.NET;
• Diagnosticism.Rust;

License

Diagnosticism.Python is released under the 3-clause BSD license. See LICENSE for details.