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.14.

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:

Constants

Diagnostic Logging API

The following constants are defined:

Contingent Reporting API

The following constants are defined:

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:

Debugging API

Diagnostic Logging API

Tracing API

Time formatting API

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.