Diagnosticism, for Python
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.
Install via pip or pip3, as in:
$ pip3 install diagnosticism
Use via import:
importdiagnosticismWhen using the simple logging facilities, we find it convenient to import as follows:
importdiagnosticismasdimportdiagnosticism.severityassevthat may then be used as:
d.log(sev.INFO, "hello")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__.
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.
The following classes are defined:
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 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.pydefmain():
dg=DOOMGram()
for_inrange(1_000):
r=random.uniform(1, 1_000)
d=r/1_000_000withDOOMScope(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 |
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". |
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 withset_log_filter()andis_severity_logged()).
The following context managers are defined:
DOOMScope- see above;
The following decorators are defined:
Decorate that provides the equivalent functionality as @tracefunc for async functions and methods.
Decorator to be applied to functions and methods to save the need to call d.trace(), for example rather than:
defstart():
d.trace()
. . .
defsubmit_work(name, job, priority=-1):
d.trace()
. . .you can, more cleanly, write:
@d.tracefuncdefstart():
. . .
@d.tracefuncdefsubmit_work(name, job, priority=-1):
. . .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. |
| 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. |
| 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. |
| 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. |
| 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:
fromdiagnosticismimportnanoseconds_to_stringnanoseconds_to_string(123_456_789) # '123.4ms'nanoseconds_to_string( 6_789) # '6.789µs'nanoseconds_to_string(999_772_000, '+') # '+999.7ms'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.
Defect reports, feature requests, and pull requests are welcome on https://github.com/synesissoftware/Diagnosticism.Python.
Diagnosticism.Python has no (non-development) runtime dependencies.
Libraries upon which Diagnosticism.Python depends:
None.
- mock — required for running the unit-test suite on Python 2.7;
Projects that depend on Diagnosticism.Python:
Diagnosticism.Python is released under the 3-clause BSD license. See LICENSE for details.