mplugin 2.0.0a0__tar.gz

mplugin-2.0.0a0/PKG-INFO

@@ -0,0 +1,88 @@
+Metadata-Version: 2.3
+Name: mplugin
+Version: 2.0.0a0
+Summary: Class library for writing Nagios (Icinga) plugins
+Keywords: Nagios,Icinga,plugin,check,monitoring
+Author: Christian Kauhaus, Matthew Pounsett, Josef Friedrich
+Author-email: Christian Kauhaus <kc@flyingcircus.io>, Matthew Pounsett <matt@conundrum.com>, Josef Friedrich <josef@friedrich.rocks>
+License: ZPL-2.1
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Plugins
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Monitoring
+Requires-Dist: typing-extensions>=4.15.0
+Requires-Python: >=3.10
+Project-URL: Documentation, https://mplugin.readthedocs.io/
+Project-URL: Download, https://pypi.org/project/mplugin/
+Project-URL: Source, https://github.com/Josef-Friedrich/mplugin
+Project-URL: Issues, https://github.com/Josef-Friedrich/mplugin/issues
+Project-URL: Changelog, https://github.com/Josef-Friedrich/mplugin/blob/main/HISTORY.txt
+Description-Content-Type: text/x-rst
+
+The mplugin library
+============================
+
+About
+-----
+
+**mplugin** is a Python class library which helps writing Nagios (or Icinga)
+compatible plugins easily in Python. It cares for much of the boilerplate code
+and default logic commonly found in Nagios checks, including:
+
+- Nagios 3 Plugin API compliant parameters and output formatting
+- Full Nagios range syntax support
+- Automatic threshold checking
+- Multiple independend measures
+- Custom status line to communicate the main point quickly
+- Long output and performance data
+- Timeout handling
+- Persistent "cookies" to retain state information between check runs
+- Resume log file processing at the point where the last run left
+- No dependencies beyond the Python standard library (except for Python 2.6).
+
+**mplugin** runs on POSIX and Windows systems. It is compatible with
+and Python 3.9 and later.
+
+Feedback and Suggestions
+------------------------
+
+mplugin is currently maintained by Josef Friedrich <josef@friedrich.rocks>.  A
+public issue tracker can be found at
+<https://github.com/Josef-Friedrich/mplugin/issues> for bugs, suggestions, and
+patches.
+
+License
+-------
+
+The mplugin package is released under the Zope Public License 2.1 (ZPL), a
+BSD-style Open Source license.
+
+
+Documentation
+-------------
+
+Comprehensive documentation is `available online`_. The examples mentioned in
+the `tutorials`_ can also be found in the `mplugin/examples` directory of
+the source distribution.
+
+.. _available online: https://mplugin.readthedocs.io/
+.. _tutorials: https://mplugin.readthedocs.io/en/stable/tutorial/
+
+Acknowledgements
+----------------
+
+mplugin was originally written and maintained by Christian Kauhaus
+<kc@flyingcircus.io>.  Additional contributions from the community are
+acknowledged in the file CONTRIBUTORS.txt
+
+.. vim: set ft=rst:

mplugin-2.0.0a0/README.rst

@@ -0,0 +1,57 @@
+The mplugin library
+============================
+
+About
+-----
+
+**mplugin** is a Python class library which helps writing Nagios (or Icinga)
+compatible plugins easily in Python. It cares for much of the boilerplate code
+and default logic commonly found in Nagios checks, including:
+
+- Nagios 3 Plugin API compliant parameters and output formatting
+- Full Nagios range syntax support
+- Automatic threshold checking
+- Multiple independend measures
+- Custom status line to communicate the main point quickly
+- Long output and performance data
+- Timeout handling
+- Persistent "cookies" to retain state information between check runs
+- Resume log file processing at the point where the last run left
+- No dependencies beyond the Python standard library (except for Python 2.6).
+
+**mplugin** runs on POSIX and Windows systems. It is compatible with
+and Python 3.9 and later.
+
+Feedback and Suggestions
+------------------------
+
+mplugin is currently maintained by Josef Friedrich <josef@friedrich.rocks>.  A
+public issue tracker can be found at
+<https://github.com/Josef-Friedrich/mplugin/issues> for bugs, suggestions, and
+patches.
+
+License
+-------
+
+The mplugin package is released under the Zope Public License 2.1 (ZPL), a
+BSD-style Open Source license.
+
+
+Documentation
+-------------
+
+Comprehensive documentation is `available online`_. The examples mentioned in
+the `tutorials`_ can also be found in the `mplugin/examples` directory of
+the source distribution.
+
+.. _available online: https://mplugin.readthedocs.io/
+.. _tutorials: https://mplugin.readthedocs.io/en/stable/tutorial/
+
+Acknowledgements
+----------------
+
+mplugin was originally written and maintained by Christian Kauhaus
+<kc@flyingcircus.io>.  Additional contributions from the community are
+acknowledged in the file CONTRIBUTORS.txt
+
+.. vim: set ft=rst:

mplugin-2.0.0a0/pyproject.toml

@@ -0,0 +1,53 @@
+
+[project]
+name = "mplugin"
+version = "2.0.0a0"
+description = "Class library for writing Nagios (Icinga) plugins"
+authors = [
+    { name = "Christian Kauhaus", email = "kc@flyingcircus.io" },
+    { name = "Matthew Pounsett", email = "matt@conundrum.com" },
+    { name = "Josef Friedrich", email = "josef@friedrich.rocks" }
+]
+maintainers = [
+
+]
+readme = "README.rst"
+license = { text = "ZPL-2.1" }
+keywords = ["Nagios", "Icinga", "plugin", "check", "monitoring"]
+requires-python = ">= 3.10"
+classifiers = [
+    'Development Status :: 5 - Production/Stable',
+    'Environment :: Plugins',
+    'Intended Audience :: Developers',
+    'Intended Audience :: System Administrators',
+    'Operating System :: Microsoft :: Windows',
+    'Operating System :: POSIX',
+    'Programming Language :: Python :: 3.9',
+    'Programming Language :: Python :: 3.10',
+    'Programming Language :: Python :: 3.11',
+    'Programming Language :: Python :: 3.12',
+    'Programming Language :: Python :: 3.13',
+    'Programming Language :: Python :: 3.14',
+    'Topic :: Software Development :: Libraries :: Python Modules',
+    'Topic :: System :: Monitoring',
+]
+dependencies = [
+    "typing-extensions>=4.15.0",
+]
+
+[build-system]
+requires = ["uv_build>=0.9.26,<0.10.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "mypy>=1.19.1",
+    "pytest>=8.4.2",
+]
+
+[project.urls]
+Documentation = "https://mplugin.readthedocs.io/"
+Download = "https://pypi.org/project/mplugin/"
+Source = "https://github.com/Josef-Friedrich/mplugin"
+Issues = "https://github.com/Josef-Friedrich/mplugin/issues"
+Changelog = "https://github.com/Josef-Friedrich/mplugin/blob/main/HISTORY.txt"

mplugin-2.0.0a0/src/mplugin/__init__.py

@@ -0,0 +1,17 @@
+from .check import Check  # noqa: F401
+from .context import Context, ScalarContext  # noqa: F401
+from .cookie import Cookie  # noqa: F401
+from .error import CheckError, Timeout  # noqa: F401
+from .logtail import LogTail  # noqa: F401
+from .metric import Metric  # noqa: F401
+from .multiarg import MultiArg  # noqa: F401
+from .performance import Performance  # noqa: F401
+from .range import Range  # noqa: F401
+from .resource import Resource  # noqa: F401
+from .result import Result, Results  # noqa: F401
+from .runtime import Runtime, guarded  # noqa: F401
+from .state import critical, ok, unknown, warn  # noqa: F401
+from .summary import Summary  # noqa: F401
+from .version import __VERSION__
+
+__version__ = __VERSION__

mplugin-2.0.0a0/src/mplugin/check.py

@@ -0,0 +1,185 @@
+"""Controller logic for check execution.
+
+This module contains the :class:`Check` class which orchestrates the
+the various stages of check execution. Interfacing with the
+outside system is done via a separate :class:`Runtime` object.
+
+When a check is called (using :meth:`Check.main` or
+:meth:`Check.__call__`), it probes all resources and evaluates the
+returned metrics to results and performance data. A typical usage
+pattern would be to populate a check with domain objects and then
+delegate control to it.
+"""
+
+import logging
+from typing import Any, NoReturn
+
+from .context import Context, Contexts
+from .error import CheckError
+from .metric import Metric
+from .resource import Resource
+from .result import Result, Results
+from .runtime import Runtime
+from .state import ServiceState, ok, unknown
+from .summary import Summary
+
+_log = logging.getLogger(__name__)
+
+
+class Check(object):
+    resources: list[Resource]
+    contexts: Contexts
+    summary: Summary
+    results: Results
+    perfdata: list[str]
+    name: str
+
+    def __init__(self, *objects: Resource | Context | Summary | Results, **kwargs):
+        """Creates and configures a check.
+
+        Specialized *objects* representing resources, contexts,
+        summary, or results are passed to the the :meth:`add` method.
+        Alternatively, objects can be added later manually.
+        If no *name* is given, the output prefix is set to the first
+        resource's name. If *name* is None, no prefix is set at all.
+        """
+        self.resources = []
+        self.contexts = Contexts()
+        self.summary = Summary()
+        self.results = Results()
+        self.perfdata = []
+        if "name" in kwargs and kwargs["name"] != "":
+            self.name = kwargs["name"]
+        else:
+            self.name = ""
+        self.add(*objects)
+
+    def add(self, *objects: Resource | Context | Summary | Results):
+        """Adds domain objects to a check.
+
+        :param objects: one or more objects that are descendants from
+            :class:`~mplugin.resource.Resource`,
+            :class:`~mplugin.context.Context`,
+            :class:`~mplugin.summary.Summary`, or
+            :class:`~mplugin.result.Results`.
+        """
+        for obj in objects:
+            if isinstance(obj, Resource):
+                self.resources.append(obj)
+                if self.name is None:
+                    self.name = ""
+                elif self.name == "":
+                    self.name = self.resources[0].name
+            elif isinstance(obj, Context):
+                self.contexts.add(obj)
+            elif isinstance(obj, Summary):
+                self.summary = obj
+            elif isinstance(obj, Results):
+                self.results = obj
+            else:
+                raise TypeError("cannot add type {0} to check".format(type(obj)), obj)
+        return self
+
+    def _evaluate_resource(self, resource: Resource) -> None:
+        try:
+            metric = None
+            metrics = resource.probe()
+            if not metrics:
+                _log.warning("resource %s did not produce any metric", resource.name)
+            if isinstance(metrics, Metric):
+                # resource returned a bare metric instead of list/generator
+                metrics = [metrics]
+            for metric in metrics:
+                context = self.contexts[metric.context]
+                metric = metric.replace(contextobj=context, resource=resource)
+                result = metric.evaluate()
+                if isinstance(result, Result):
+                    self.results.add(result)
+                elif isinstance(result, ServiceState):
+                    self.results.add(Result(result, metric=metric))
+                else:
+                    raise ValueError(
+                        "evaluate() returned neither Result nor ServiceState object",
+                        metric.name,
+                        result,
+                    )
+                self.perfdata.append(str(metric.performance() or ""))
+        except CheckError as e:
+            self.results.add(Result(unknown, str(e), metric))
+
+    def __call__(self):
+        """Actually run the check.
+
+        After a check has been called, the :attr:`results` and
+        :attr:`perfdata` attributes are populated with the outcomes. In
+        most cases, you should not use __call__ directly but invoke
+        :meth:`main`, which delegates check execution to the
+        :class:`Runtime` environment.
+        """
+        for resource in self.resources:
+            self._evaluate_resource(resource)
+        self.perfdata = sorted([p for p in self.perfdata if p])
+
+    def main(self, verbose: Any = None, timeout: Any = None) -> NoReturn:
+        """All-in-one control delegation to the runtime environment.
+
+        Get a :class:`~mplugin.runtime.Runtime` instance and
+        perform all phases: run the check (via :meth:`__call__`), print
+        results and exit the program with an appropriate status code.
+
+        :param verbose: output verbosity level between 0 and 3
+        :param timeout: abort check execution with a :exc:`Timeout`
+            exception after so many seconds (use 0 for no timeout)
+        """
+        runtime = Runtime()
+        runtime.execute(self, verbose, timeout)
+
+    @property
+    def state(self) -> ServiceState:
+        """Overall check state.
+
+        The most significant (=worst) state seen in :attr:`results` to
+        far. :obj:`~mplugin.state.Unknown` if no results have been
+        collected yet. Corresponds with :attr:`exitcode`. Read-only
+        property.
+        """
+        try:
+            return self.results.most_significant_state
+        except ValueError:
+            return unknown
+
+    @property
+    def summary_str(self) -> str:
+        """Status line summary string.
+
+        The first line of output that summarizes that situation as
+        perceived by the check. The string is usually queried from a
+        :class:`Summary` object. Read-only property.
+        """
+        if not self.results:
+            return self.summary.empty() or ""
+
+        if self.state == ok:
+            return self.summary.ok(self.results) or ""
+
+        return self.summary.problem(self.results) or ""
+
+    @property
+    def verbose_str(self):
+        """Additional lines of output.
+
+        Long text output if check runs in verbose mode. Also queried
+        from :class:`~mplugin.summary.Summary`. Read-only property.
+        """
+        return self.summary.verbose(self.results) or ""
+
+    @property
+    def exitcode(self) -> int:
+        """Overall check exit code according to the Nagios API.
+
+        Corresponds with :attr:`state`. Read-only property.
+        """
+        try:
+            return int(self.results.most_significant_state)
+        except ValueError:
+            return 3

mplugin-2.0.0a0/src/mplugin/context.py

@@ -0,0 +1,223 @@
+"""Metadata about metrics to perform data :term:`evaluation`.
+
+This module contains the :class:`Context` class, which is the base for
+all contexts. :class:`ScalarContext` is an important specialization to
+cover numeric contexts with warning and critical thresholds. The
+:class:`~.check.Check` controller selects a context for each
+:class:`~.metric.Metric` by matching the metric's `context` attribute with the
+context's `name`. The same context may be used for several metrics.
+
+Plugin authors may just use to :class:`ScalarContext` in the majority of cases.
+Sometimes is better to subclass :class:`Context` instead to implement custom
+evaluation or performance data logic.
+"""
+
+import typing
+from typing import Callable, Optional
+
+from .performance import Performance
+from .range import Range
+from .result import Result
+from .state import critical, ok, warn
+
+if typing.TYPE_CHECKING:
+    from .context import Context
+    from .metric import Metric
+    from .resource import Resource
+
+FmtMetric = str | Callable[["Metric", "Context"], str]
+
+
+class Context(object):
+    name: str
+    fmt_metric: Optional[FmtMetric]
+    result_cls: type[Result]
+
+    def __init__(
+        self,
+        name: str,
+        fmt_metric: Optional[FmtMetric] = None,
+        result_cls: type[Result] = Result,
+    ) -> None:
+        """Creates generic context identified by `name`.
+
+        Generic contexts just format associated metrics and evaluate
+        always to :obj:`~mplugin.state.Ok`. Metric formatting is
+        controlled with the :attr:`fmt_metric` attribute. It can either
+        be a string or a callable. See the :meth:`describe` method for
+        how formatting is done.
+
+        :param name: context name that is matched by the context
+            attribute of :class:`~mplugin.metric.Metric`
+        :param fmt_metric: string or callable to convert
+            context and associated metric to a human readable string
+        :param result_cls: use this class (usually a
+            :class:`~.result.Result` subclass) to represent the<
+            evaluation outcome
+        """
+        self.name = name
+        self.fmt_metric = fmt_metric
+        self.result_cls = result_cls
+
+    def evaluate(self, metric: "Metric", resource: "Resource") -> Result:
+        """Determines state of a given metric.
+
+        This base implementation returns :class:`~mplugin.state.Ok`
+        in all cases. Plugin authors may override this method in
+        subclasses to specialize behaviour.
+
+        :param metric: associated metric that is to be evaluated
+        :param resource: resource that produced the associated metric
+            (may optionally be consulted)
+        :returns: :class:`~.result.Result` or
+            :class:`~.state.ServiceState` object
+        """
+        return self.result_cls(ok, metric=metric)
+
+    # This could be corrected by re-implementing this class as a proper ABC.
+    # See issue #43
+    # pylint: disable-next=no-self-use
+    def performance(
+        self, metric: "Metric", resource: "Resource"
+    ) -> Optional[Performance]:
+        """Derives performance data from a given metric.
+
+        This base implementation just returns none. Plugin authors may
+        override this method in subclass to specialize behaviour.
+
+        :param metric: associated metric from which performance data are
+            derived
+        :param resource: resource that produced the associated metric
+            (may optionally be consulted)
+        :returns: :class:`~.performance.Performance` object or `None`
+        """
+        return None
+
+    def describe(self, metric: "Metric") -> Optional[str]:
+        """Provides human-readable metric description.
+
+        Formats the metric according to the :attr:`fmt_metric`
+        attribute. If :attr:`fmt_metric` is a string, it is evaluated as
+        format string with all metric attributes in the root namespace.
+        If :attr:`fmt_metric` is callable, it is called with the metric
+        and this context as arguments. If :attr:`fmt_metric` is not set,
+        this default implementation does not return a description.
+
+        Plugin authors may override this method in subclasses to control
+        text output more tightly.
+
+        :param metric: associated metric
+        :returns: description string or None
+        """
+        if not self.fmt_metric:
+            return None
+
+        if isinstance(self.fmt_metric, str):
+            return self.fmt_metric.format(
+                name=metric.name,
+                value=metric.value,
+                uom=metric.uom,
+                valueunit=metric.valueunit,
+                min=metric.min,
+                max=metric.max,
+            )
+
+        return self.fmt_metric(metric, self)
+
+
+class ScalarContext(Context):
+    def __init__(
+        self,
+        name: str,
+        warning=None,
+        critical=None,
+        fmt_metric: FmtMetric = "{name} is {valueunit}",
+        result_cls: type[Result] = Result,
+    ):
+        """Ready-to-use :class:`Context` subclass for scalar values.
+
+        ScalarContext models the common case where a single scalar is to
+        be evaluated against a pair of warning and critical thresholds.
+
+        :attr:`name`, :attr:`fmt_metric`, and :attr:`result_cls`,
+        are described in the :class:`Context` base class.
+
+        :param warning: Warning threshold as
+            :class:`~mplugin.range.Range` object or range string.
+        :param critical: Critical threshold as
+            :class:`~mplugin.range.Range` object or range string.
+        """
+        super(ScalarContext, self).__init__(name, fmt_metric, result_cls)
+        self.warning = Range(warning)
+        self.critical = Range(critical)
+
+    def evaluate(self, metric, resource):
+        """Compares metric with ranges and determines result state.
+
+        The metric's value is compared to the instance's :attr:`warning`
+        and :attr:`critical` ranges, yielding an appropropiate state
+        depending on how the metric fits in the ranges. Plugin authors
+        may override this method in subclasses to provide custom
+        evaluation logic.
+
+        :param metric: metric that is to be evaluated
+        :param resource: not used
+        :returns: :class:`~mplugin.result.Result` object
+        """
+        if not self.critical.match(metric.value):
+            return self.result_cls(critical, self.critical.violation, metric)
+        if not self.warning.match(metric.value):
+            return self.result_cls(warn, self.warning.violation, metric)
+        return self.result_cls(ok, None, metric)
+
+    def performance(self, metric, resource):
+        """Derives performance data.
+
+        The metric's attributes are combined with the local
+        :attr:`warning` and :attr:`critical` ranges to get a
+        fully populated :class:`~mplugin.performance.Performance`
+        object.
+
+        :param metric: metric from which performance data are derived
+        :param resource: not used
+        :returns: :class:`~mplugin.performance.Performance` object
+        """
+        return Performance(
+            metric.name,
+            metric.value,
+            metric.uom,
+            self.warning,
+            self.critical,
+            metric.min,
+            metric.max,
+        )
+
+
+class Contexts:
+    """Container for collecting all generated contexts."""
+
+    by_name: dict[str, Context]
+
+    def __init__(self):
+        self.by_name = dict(
+            default=ScalarContext("default", "", ""), null=Context("null")
+        )
+
+    def add(self, context: Context) -> None:
+        self.by_name[context.name] = context
+
+    def __getitem__(self, context_name: str) -> Context:
+        try:
+            return self.by_name[context_name]
+        except KeyError:
+            raise KeyError(
+                "cannot find context",
+                context_name,
+                "known contexts: {0}".format(", ".join(self.by_name.keys())),
+            )
+
+    def __contains__(self, context_name: str) -> bool:
+        return context_name in self.by_name
+
+    def __iter__(self) -> typing.Iterator[str]:
+        return iter(self.by_name)