# Diagnosticism.Python <!-- omit from toc -->
<!--
[](https://circleci.com/gh/google/diagnosticism)
-->
[](https://opensource.org/licenses/BSD-3-Clause)
[](https://badge.fury.io/py/diagnosticism)
[](https://github.com/synesissoftware/Diagnosticism.Python/actions/workflows/python-package.yml)
[](https://github.com/synesissoftware/Diagnosticism.Python/commits/master)
Diagnosticism library, for Python
## Table of Contents <!-- omit from toc -->
- [Introduction](#introduction)
- [Installation \& usage](#installation--usage)
- [Components](#components)
- [Classes](#classes)
- [`DOOMGram`](#doomgram)
- [`DOOMScope`](#doomscope)
- [Constants](#constants)
- [Diagnostic Logging API](#diagnostic-logging-api)
- [Contingent Reporting API](#contingent-reporting-api)
- [Context Managers](#context-managers)
- [Decorators](#decorators)
- [`asynctracefunc`](#asynctracefunc)
- [`tracefunc`](#tracefunc)
- [Functions](#functions)
- [Contingent Reporting API](#contingent-reporting-api-1)
- [Debugging API](#debugging-api)
- [Diagnostic Logging API](#diagnostic-logging-api-1)
- [Tracing API](#tracing-api)
- [Examples](#examples)
- [Project Information](#project-information)
- [Where to get help](#where-to-get-help)
- [Contribution guidelines](#contribution-guidelines)
- [Dependencies](#dependencies)
- [Related projects](#related-projects)
- [License](#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 **Diagnosticism**s - see [below](#related-projects) - 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**:
```Python
import diagnosticism
```
When using the simple logging facilities, we find it convenient to import as follows:
```Python
import diagnosticism as d
import diagnosticism.severity as sev
```
that may then be used as:
```Python
d.log(sev.INFO, "hello")
```
## Components
**Diagnosticism.Python** provides components in the following categories:
* Contingent Reporting
* Diagnostic Logging
* 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**](./examples/doomgram.py) illustrates these two types in combination
```Python
# examples/doomgram.py
def main():
dg = DOOMGram()
for _ in range(1000):
r = random.uniform(1, 1000)
d = r / 1_000_000
with DOOMScope(dg):
time.sleep(d)
print("dg:", dg)
. . .
```
and produces output such as:
```bash
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](#doomscope);
### Decorators
The following decorators are defined:
#### `asynctracefunc`
T.B.C.
#### `tracefunc`
T.B.C.
### 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, any number of normal and keyword arguments and traces their type, value, and name. |
| `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. |
## 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](./EXAMPLES.md).
## Project Information
### Where to get help
[GitHub Page](https://github.com/synesissoftware/Diagnosticism.Python "GitHub Page")
### Contribution guidelines
Defect reports, feature requests, and pull requests are welcome on https://github.com/synesissoftware/Diagnosticism.Python.
### Dependencies
### Related projects
* [**Diagnosticism**](https://github.com/synesissoftware/Diagnosticism/) (**C**);
* [**Diagnosticism.Go**](https://github.com/synesissoftware/Diagnosticism.Go/);
* [**Diagnosticism.NET**](https://github.com/synesissoftware/Diagnosticism.NET/);
* [**Diagnosticism.Rust**](https://github.com/synesissoftware/Diagnosticism.Rust/);
### License
**Diagnosticism.Python** is released under the 3-clause BSD license. See [LICENSE](./LICENSE) for details.
<!-- ########################### end of file ########################### -->
Raw data
{
"_id": null,
"home_page": "https://github.com/synesissoftware/diagnosticism.Python",
"name": "diagnosticism",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "Diagnostic Diagnostics Logging Trace Tracing Stopwatch",
"author": "Matt Wilson",
"author_email": "matthew@synesis.com.au",
"download_url": "https://files.pythonhosted.org/packages/d6/7b/25de6f0b91f9571832e76f4ad844827a8c6aaa7bba4dcf92c541d8ce7e81/diagnosticism-0.15.2.tar.gz",
"platform": null,
"description": "# Diagnosticism.Python <!-- omit from toc -->\n\n<!--\n[](https://circleci.com/gh/google/diagnosticism)\n-->\n[](https://opensource.org/licenses/BSD-3-Clause)\n[](https://badge.fury.io/py/diagnosticism)\n\n[](https://github.com/synesissoftware/Diagnosticism.Python/actions/workflows/python-package.yml)\n[](https://github.com/synesissoftware/Diagnosticism.Python/commits/master)\n\nDiagnosticism library, for Python\n\n\n## Table of Contents <!-- omit from toc -->\n\n- [Introduction](#introduction)\n- [Installation \\& usage](#installation--usage)\n- [Components](#components)\n\t- [Classes](#classes)\n\t\t- [`DOOMGram`](#doomgram)\n\t\t- [`DOOMScope`](#doomscope)\n\t- [Constants](#constants)\n\t\t- [Diagnostic Logging API](#diagnostic-logging-api)\n\t\t- [Contingent Reporting API](#contingent-reporting-api)\n\t- [Context Managers](#context-managers)\n\t- [Decorators](#decorators)\n\t\t- [`asynctracefunc`](#asynctracefunc)\n\t\t- [`tracefunc`](#tracefunc)\n\t- [Functions](#functions)\n\t\t- [Contingent Reporting API](#contingent-reporting-api-1)\n\t\t- [Debugging API](#debugging-api)\n\t\t- [Diagnostic Logging API](#diagnostic-logging-api-1)\n\t\t- [Tracing API](#tracing-api)\n- [Examples](#examples)\n- [Project Information](#project-information)\n\t- [Where to get help](#where-to-get-help)\n\t- [Contribution guidelines](#contribution-guidelines)\n\t- [Dependencies](#dependencies)\n\t- [Related projects](#related-projects)\n\t- [License](#license)\n\n\n## Introduction\n\n**Diagnosticism** is a standalone library of simple components for aiding in diagnostics for Python projects. It contains versions of components seen in the other **Diagnosticism**s - see [below](#related-projects) - though there is not a 1-to-1 correspondence between any of them.\n\n\n## Installation & usage\n\nInstall via **pip** or **pip3**, as in:\n\n```\n$ pip3 install diagnosticism\n```\n\nUse via **import**:\n\n```Python\n\nimport diagnosticism\n```\n\nWhen using the simple logging facilities, we find it convenient to import as follows:\n\n```Python\n\nimport diagnosticism as d\nimport diagnosticism.severity as sev\n```\n\nthat may then be used as:\n\n```Python\n\nd.log(sev.INFO, \"hello\")\n```\n\n\n\n## Components\n\n**Diagnosticism.Python** provides components in the following categories:\n\n* Contingent Reporting\n* Diagnostic Logging\n* Tracing\n\n**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**.\n\n\n### Classes\n\nThe following classes are defined:\n\n#### `DOOMGram`\n\n`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:\n\n#### `DOOMScope`\n\n`DOOMScope` is a context-manager for use with `DOOMGram` for measuring scoped chunks of logic.\n\nThe example program [**examples/doomgram.py**](./examples/doomgram.py) illustrates these two types in combination\n\n```Python\n# examples/doomgram.py\n\ndef main():\n\n dg = DOOMGram()\n\n for _ in range(1000):\n\n r = random.uniform(1, 1000)\n\n d = r / 1_000_000\n\n with DOOMScope(dg):\n\n time.sleep(d)\n\n print(\"dg:\", dg)\n\n. . .\n```\n\nand produces output such as:\n\n```bash\ndg: ___abcc_____\n```\n\nwhich indicates the following breakdown of operation - in this case a random `sleep()` - timings:\n\n| Time period(s) | Number of events in that period |\n| ----------- | ------------ |\n| Nanoseconds | no records |\n| Microseconds | 1-9 in 1\u00b5s (`a`); 10-99 in 10\u00b5s (`b`); 100-899 in 100\u00b5s (`c`) |\n| Milliseconds | 100-999 in 1ms (`c`) |\n| Seconds | no records |\n\n\n### Constants\n\n#### Diagnostic Logging API\n\nThe following constants are defined:\n\n| Constant | API | Purpose |\n| -------- | --- | ------- |\n| STOCK_TRAILING_PROMPT | **Contingent Reporting** | The stock trailing prompt, which is defined as `\"use --help for usage\"`. |\n\n#### Contingent Reporting API\n\nThe following constants are defined:\n\n| Constant | API | Purpose |\n| -------- | --- | ------- |\n| VIOLATION | **Diagnostic Logging** | Severity level suitable for use when logging that a design violation has occurred. |\n| ALERT | **Diagnostic Logging** | Severity level suitable for use when logging that a fatal program failure has occurred. |\n| CRITICAL | **Diagnostic Logging** | Severity level suitable for use when logging that a critical failure has occurred. |\n| FAILURE | **Diagnostic Logging** | Severity level suitable for use when logging that a failure has occurred. |\n| WARNING | **Diagnostic Logging** | Severity level suitable for use when issuing a warning. |\n| NOTICE | **Diagnostic Logging** | Severity level suitable for use when logging an important normative condition. |\n| INFORMATIONAL | **Diagnostic Logging** | Severity level suitable for use when logging a normative condition. |\n| DEBUG0 | **Diagnostic Logging** | The highest debug severity level. |\n| DEBUG1 | **Diagnostic Logging** | The second highest debug severity level. |\n| DEBUG2 | **Diagnostic Logging** | The third highest debug severity level. |\n| DEBUG3 | **Diagnostic Logging** | The fourth highest debug severity level. |\n| DEBUG4 | **Diagnostic Logging** | The fifth highest debug severity level. |\n| DEBUG5 | **Diagnostic Logging** | The sixth highest debug severity level. |\n| TRACE | **Diagnostic Logging** | Severity level suitable at which trace statements are issued. |\n| BENCHMARK | **Diagnostic Logging** | Severity level suitable at which benchmark statements are issued. |\n| DEBUG | **Diagnostics Logging** | Alias for `DEBUG5` |\n| FAIL | **Diagnostics Logging** | Alias for `FAILURE` |\n| WARN | **Diagnostics Logging** | Alias for `WARNING` |\n| INFO | **Diagnostics Logging** | Alias for `INFORMATIONAL` |\n\n> **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()`).\n\n\n### Context Managers\n\nThe following context managers are defined:\n\n* `DOOMScope` - see [above](#doomscope);\n\n\n### Decorators\n\nThe following decorators are defined:\n\n\n#### `asynctracefunc`\n\nT.B.C.\n\n\n#### `tracefunc`\n\nT.B.C.\n\n\n\n\n\n### Functions\n\n#### Contingent Reporting API\n\nThe following functions are defined:\n\n| Function | Purpose |\n| -------- | ------- |\n| `abort()` | Issues a contingent report (via `conrep()`) and then terminating the process. |\n| `report()` | Issues a message string as a contingent report, by defaulting writing output to `sys.stderr`. |\n| `set_default_trailing_prompt()` | Sets the default trailing prompt. |\n| `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. |\n\n\n#### Debugging API\n\n| Function | Purpose |\n| -------- | ------- |\n| `file()` | Obtains the file in which the calling function is defined. |\n| `fileline()` | Obtains the file+line in which the calling function is defined. |\n| `filelinefunc()` | Obtains the file+line+function in which the calling function is defined. |\n| `func()` | Obtains the function in which the calling function is defined. |\n| `line()` | Obtains the line on which the calling function is defined. |\n\n\n#### Diagnostic Logging API\n\n| Function | Purpose |\n| -------- | ------- |\n| `enable_logging()` | Enables/disables logging, whether from a constant or from a named environment variable. |\n| `is_logging_enabled()` | Indicates whether logging is enabled. |\n| `is_severity_logged()` | Indicates whether a log statement at a given severity will be logged. |\n| `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`). |\n| `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. |\n\n\n#### Tracing API\n\n| Function | Purpose |\n| -------- | ------- |\n| `dbg()` | Similar to **Rust**'s `dbg!()` macro, any number of normal and keyword arguments and traces their type, value, and name. |\n| `dbgfl()` | Like `dbg()`, but include `fileline()` information in the `TRACE` statement produced. |\n| `enable_tracing()` | Enables/disables tracing, whether from a constant or from a named environment variable. |\n| `is_tracing_enabled()` | Indicates whether tracing is enabled. |\n| `trace()` | Traces the name and signature of the calling function, including the values of all its arguments. |\n\n\n## Examples\n\nExamples are provided in the ```examples``` directory, along with a markdown description for each. A detailed list TOC of them is provided in [EXAMPLES.md](./EXAMPLES.md).\n\n\n## Project Information\n\n\n### Where to get help\n\n[GitHub Page](https://github.com/synesissoftware/Diagnosticism.Python \"GitHub Page\")\n\n\n### Contribution guidelines\n\nDefect reports, feature requests, and pull requests are welcome on https://github.com/synesissoftware/Diagnosticism.Python.\n\n\n### Dependencies\n\n\n### Related projects\n\n* [**Diagnosticism**](https://github.com/synesissoftware/Diagnosticism/) (**C**);\n* [**Diagnosticism.Go**](https://github.com/synesissoftware/Diagnosticism.Go/);\n* [**Diagnosticism.NET**](https://github.com/synesissoftware/Diagnosticism.NET/);\n* [**Diagnosticism.Rust**](https://github.com/synesissoftware/Diagnosticism.Rust/);\n\n\n### License\n\n**Diagnosticism.Python** is released under the 3-clause BSD license. See [LICENSE](./LICENSE) for details.\n\n\n<!-- ########################### end of file ########################### -->\n\n\n\n",
"bugtrack_url": null,
"license": "BSD-3-Clause",
"summary": "Basic diagnostic facilities, for Python",
"version": "0.15.2",
"project_urls": {
"Homepage": "https://github.com/synesissoftware/diagnosticism.Python"
},
"split_keywords": [
"diagnostic",
"diagnostics",
"logging",
"trace",
"tracing",
"stopwatch"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "d67b25de6f0b91f9571832e76f4ad844827a8c6aaa7bba4dcf92c541d8ce7e81",
"md5": "3751eee16052e56e1b3141537dca2552",
"sha256": "95a35e1e871849fe8edb1587670c1fdd7e4d6d568c7be84d9fe6133e21cf1dcd"
},
"downloads": -1,
"filename": "diagnosticism-0.15.2.tar.gz",
"has_sig": false,
"md5_digest": "3751eee16052e56e1b3141537dca2552",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 26058,
"upload_time": "2025-08-27T09:28:28",
"upload_time_iso_8601": "2025-08-27T09:28:28.346786Z",
"url": "https://files.pythonhosted.org/packages/d6/7b/25de6f0b91f9571832e76f4ad844827a8c6aaa7bba4dcf92c541d8ce7e81/diagnosticism-0.15.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-27 09:28:28",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "synesissoftware",
"github_project": "diagnosticism.Python",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "diagnosticism"
}
JSON
