watchpost 0.1.0__tar.gz

watchpost-0.1.0/PKG-INFO

@@ -0,0 +1,166 @@
+Metadata-Version: 2.4
+Name: watchpost
+Version: 0.1.0
+Summary: Code driven monitoring checks for Checkmk
+Keywords: monitoring,checkmk,observability,infrastructure,devops
+Author: Pit Kleyersburg
+Author-email: Pit Kleyersburg <pitkley@googlemail.com>
+License-Expression: Apache-2.0
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Monitoring
+Classifier: Topic :: System :: Systems Administration
+Classifier: Typing :: Typed
+Requires-Dist: starlette>=0.47.3,<0.48.0
+Requires-Dist: timelength>=3.0.2,<3.1.0
+Requires-Dist: click>=8.2.1,<9.0.0 ; extra == 'cli'
+Requires-Dist: rich>=14.1.0,<15.0.0 ; extra == 'cli'
+Requires-Dist: redis>=6.4.0,<7.0.0 ; extra == 'redis'
+Requires-Python: >=3.13
+Project-URL: Changelog, https://github.com/pitkley/watchpost/releases
+Project-URL: Documentation, https://pitkley.github.io/watchpost/
+Project-URL: Homepage, https://github.com/pitkley/watchpost
+Project-URL: Issues, https://github.com/pitkley/watchpost/issues
+Project-URL: Repository, https://github.com/pitkley/watchpost.git
+Provides-Extra: cli
+Provides-Extra: redis
+Description-Content-Type: text/markdown
+
+# Watchpost &ndash; code-driven monitoring checks for Checkmk
+
+Watchpost is a small framework for writing monitoring checks as Python code and integrating them with [Checkmk](https://checkmk.com/).
+It helps you configure checks through a simple function decorator, handles running checks across and against multiple environments, and supports you in gathering data from external systems.
+
+## Example
+
+Install Watchpost in your project:
+
+```shell
+pip install 'watchpost[cli]'
+```
+
+You can now write a basic Watchpost application like this:
+
+```python
+import urllib.error
+import urllib.request
+
+from watchpost import EnvironmentRegistry, Watchpost, check, crit, ok
+
+ENVIRONMENTS = EnvironmentRegistry()
+PRODUCTION = ENVIRONMENTS.new("production")
+
+
+@check(  # (1)
+    name="example.com HTTP status",
+    service_labels={},
+    environments=[PRODUCTION],
+    cache_for="5m",
+)
+async def example_com_http_status():
+    try:
+        with urllib.request.urlopen("https://www.example.com") as response:
+            status_code = response.status
+    except urllib.error.HTTPError as e:
+        status_code = e.code
+
+    if status_code != 200:
+        return crit(  # (2)
+            "example.com returned an error",
+            details=f"Expected status: 200\nActual status: {status_code}\n",
+        )
+
+    return ok("example.com is up")  # (3)
+
+
+app = Watchpost(
+    checks=[
+        example_com_http_status,  # (4)
+    ],
+    execution_environment=PRODUCTION,
+)
+```
+
+1. Use the `@check` decorator to define your check:
+
+    * A human-friendly name that will appear as the service name in Checkmk.
+    * Optional service labels to attach to the Checkmk service.
+    * The environments this check targets.
+    * A cache duration that controls how long a result is kept before the check runs again.
+
+2. If the check fails, return `crit(...)`. The details will be shown in the Checkmk service to help troubleshooting.
+3. If everything is fine, return `ok(...)`.
+4. Register the check with the application.
+
+Assuming this is saved as `example.py`, you can run it locally as such using the `watchpost` CLI:
+
+```console
+$ watchpost --app example:app run-checks
+                       Check Execution Results
+┏━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━┓
+┃ State ┃ Environment ┃ Service Name            ┃ Summary           ┃
+┡━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━┩
+│  OK   │ production  │ example.com HTTP status │ example.com is up │
+└───────┴─────────────┴─────────────────────────┴───────────────────┘
+```
+
+The Checkmk integration makes use of HTTP to retrieve the check results from the Watchpost application.
+To support this, Watchpost is a valid ASGI web application which you can run with any ASGI server, for example [uvicorn](https://www.uvicorn.org/):
+
+```console
+$ pip install uvicorn
+$ uvicorn example:app
+INFO:     Started server process [12345]
+INFO:     Waiting for application startup.
+INFO:     Application startup complete.
+INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
+```
+
+## Capabilities at a glance
+
+* Checks and results
+    * `@check` decorator, multiple result modes (single, multiple, yielded, builder)
+    * Result helpers: `ok`, `warn`, `crit`, `unknown`, metrics, thresholds
+* Environments and scheduling
+    * Target vs. execution environments, pluggable scheduling strategies with validation
+* Datasources
+    * Simple base class (`Datasource`) and factory pattern to share configuration
+* Execution and streaming
+    * Key‑aware executor, error aggregation, Checkmk output generation
+* Caching
+    * In‑memory, disk, and optional Redis backends; memoization helper
+* ASGI / HTTP
+    * Starlette app; routes: `/`, `/healthcheck`, `/executor/statistics`, `/executor/errored`
+
+## Documentation
+
+See [`./docs`](docs/) for more information.
+
+## License
+
+Watchpost is licensed under the Apache License, Version 2.0, (see [LICENSE](LICENSE) or <https://www.apache.org/licenses/LICENSE-2.0>).
+
+Watchpost internally makes use of various open-source projects.
+You can find a full list of these projects and their licenses in [THIRD_PARTY_LICENSES.md](THIRD_PARTY_LICENSES.md).
+
+### Contribution
+
+Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in Watchpost by you, as defined in the Apache-2.0 license, shall be licensed under the Apache License, Version 2.0, without any additional terms or conditions.
+
+We make use of [Lefthook](https://lefthook.dev/) for pre-commit and pre-push hooks that verify your code is valid.
+To set up the hooks, run `uv run lefthook install`.
+
+## Affiliation
+
+This project has no official affiliation with Checkmk GmbH or any of its affiliates.
+"Checkmk" is a trademark of Checkmk GmbH.
+
+## History
+
+This project is a fork of [takkt-ag/watchpost](https://github.com/takkt-ag/watchpost).

watchpost-0.1.0/README.md

@@ -0,0 +1,132 @@
+# Watchpost – code-driven monitoring checks for Checkmk
+
+Watchpost is a small framework for writing monitoring checks as Python code and integrating them with [Checkmk](https://checkmk.com/).
+It helps you configure checks through a simple function decorator, handles running checks across and against multiple environments, and supports you in gathering data from external systems.
+
+## Example
+
+Install Watchpost in your project:
+
+```shell
+pip install 'watchpost[cli]'
+```
+
+You can now write a basic Watchpost application like this:
+
+```python
+import urllib.error
+import urllib.request
+
+from watchpost import EnvironmentRegistry, Watchpost, check, crit, ok
+
+ENVIRONMENTS = EnvironmentRegistry()
+PRODUCTION = ENVIRONMENTS.new("production")
+
+
+@check(  # (1)
+    name="example.com HTTP status",
+    service_labels={},
+    environments=[PRODUCTION],
+    cache_for="5m",
+)
+async def example_com_http_status():
+    try:
+        with urllib.request.urlopen("https://www.example.com") as response:
+            status_code = response.status
+    except urllib.error.HTTPError as e:
+        status_code = e.code
+
+    if status_code != 200:
+        return crit(  # (2)
+            "example.com returned an error",
+            details=f"Expected status: 200\nActual status: {status_code}\n",
+        )
+
+    return ok("example.com is up")  # (3)
+
+
+app = Watchpost(
+    checks=[
+        example_com_http_status,  # (4)
+    ],
+    execution_environment=PRODUCTION,
+)
+```
+
+1. Use the `@check` decorator to define your check:
+
+    * A human-friendly name that will appear as the service name in Checkmk.
+    * Optional service labels to attach to the Checkmk service.
+    * The environments this check targets.
+    * A cache duration that controls how long a result is kept before the check runs again.
+
+2. If the check fails, return `crit(...)`. The details will be shown in the Checkmk service to help troubleshooting.
+3. If everything is fine, return `ok(...)`.
+4. Register the check with the application.
+
+Assuming this is saved as `example.py`, you can run it locally as such using the `watchpost` CLI:
+
+```console
+$ watchpost --app example:app run-checks
+                       Check Execution Results
+┏━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━┓
+┃ State ┃ Environment ┃ Service Name            ┃ Summary           ┃
+┡━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━┩
+│  OK   │ production  │ example.com HTTP status │ example.com is up │
+└───────┴─────────────┴─────────────────────────┴───────────────────┘
+```
+
+The Checkmk integration makes use of HTTP to retrieve the check results from the Watchpost application.
+To support this, Watchpost is a valid ASGI web application which you can run with any ASGI server, for example [uvicorn](https://www.uvicorn.org/):
+
+```console
+$ pip install uvicorn
+$ uvicorn example:app
+INFO:     Started server process [12345]
+INFO:     Waiting for application startup.
+INFO:     Application startup complete.
+INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
+```
+
+## Capabilities at a glance
+
+* Checks and results
+    * `@check` decorator, multiple result modes (single, multiple, yielded, builder)
+    * Result helpers: `ok`, `warn`, `crit`, `unknown`, metrics, thresholds
+* Environments and scheduling
+    * Target vs. execution environments, pluggable scheduling strategies with validation
+* Datasources
+    * Simple base class (`Datasource`) and factory pattern to share configuration
+* Execution and streaming
+    * Key‑aware executor, error aggregation, Checkmk output generation
+* Caching
+    * In‑memory, disk, and optional Redis backends; memoization helper
+* ASGI / HTTP
+    * Starlette app; routes: `/`, `/healthcheck`, `/executor/statistics`, `/executor/errored`
+
+## Documentation
+
+See [`./docs`](docs/) for more information.
+
+## License
+
+Watchpost is licensed under the Apache License, Version 2.0, (see [LICENSE](LICENSE) or <https://www.apache.org/licenses/LICENSE-2.0>).
+
+Watchpost internally makes use of various open-source projects.
+You can find a full list of these projects and their licenses in [THIRD_PARTY_LICENSES.md](THIRD_PARTY_LICENSES.md).
+
+### Contribution
+
+Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in Watchpost by you, as defined in the Apache-2.0 license, shall be licensed under the Apache License, Version 2.0, without any additional terms or conditions.
+
+We make use of [Lefthook](https://lefthook.dev/) for pre-commit and pre-push hooks that verify your code is valid.
+To set up the hooks, run `uv run lefthook install`.
+
+## Affiliation
+
+This project has no official affiliation with Checkmk GmbH or any of its affiliates.
+"Checkmk" is a trademark of Checkmk GmbH.
+
+## History
+
+This project is a fork of [takkt-ag/watchpost](https://github.com/takkt-ag/watchpost).

watchpost-0.1.0/pyproject.toml

@@ -0,0 +1,130 @@
+[project]
+name = "watchpost"
+version = "0.1.0"
+description = "Code driven monitoring checks for Checkmk"
+readme = "README.md"
+license = "Apache-2.0"
+authors = [
+    { name = "Pit Kleyersburg", email = "pitkley@googlemail.com" },
+]
+requires-python = ">=3.13"
+keywords = [
+    "monitoring",
+    "checkmk",
+    "observability",
+    "infrastructure",
+    "devops",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Framework :: AsyncIO",
+    "Intended Audience :: Developers",
+    "Intended Audience :: System Administrators",
+    "License :: OSI Approved :: Apache Software License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: System :: Monitoring",
+    "Topic :: System :: Systems Administration",
+    "Typing :: Typed",
+]
+dependencies = [
+    "starlette>=0.47.3,<0.48.0",
+    "timelength>=3.0.2,<3.1.0",
+]
+
+[project.optional-dependencies]
+cli = [
+    "click>=8.2.1,<9.0.0",
+    "rich>=14.1.0,<15.0.0",
+]
+redis = [
+    "redis>=6.4.0,<7.0.0",
+]
+
+[project.scripts]
+watchpost = "watchpost.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/pitkley/watchpost"
+Documentation = "https://pitkley.github.io/watchpost/"
+Repository = "https://github.com/pitkley/watchpost.git"
+Issues = "https://github.com/pitkley/watchpost/issues"
+Changelog = "https://github.com/pitkley/watchpost/releases"
+
+[build-system]
+requires = ["uv_build>=0.8.2,<0.9.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "httpx>=0.28.1,<0.29.0",
+    "lefthook>=1.12.4,<2.0.0",
+    "licensecheck>=2025.1.0,<2025.2.0",
+    "mypy>=1.17.1,<2.0.0",
+    "pytest>=8.4.2,<9.0.0",
+    "ruff>=0.13.0,<0.14.0",
+    "testcontainers[redis]>=4.13.0,<5.0.0",
+    "ty>=0.0.1a20",
+]
+docs = [
+    "mkdocs>=1.6.1",
+    "mkdocs-autorefs>=1.4.3",
+    "mkdocs-code-validator>=0.2.0",
+    "mkdocs-material>=9.6.19",
+    "mkdocs-section-index>=0.3.10",
+    "mkdocstrings[python]>=0.30.0",
+]
+
+[tool.licensecheck]
+only_licenses = [
+    "Apache-2.0",
+    "BSD-2-Clause",
+    "ISC",
+    "MIT",
+    "MPL-2.0",
+    "PSF-2.0",
+]
+ignore_packages = [
+    "mypy-extensions", # MIT licensed, information missing
+]
+groups = [
+    "dev",
+]
+
+[tool.mypy]
+disallow_untyped_calls = true
+disallow_untyped_defs = true
+disallow_incomplete_defs = true
+disallow_untyped_decorators = true
+
+exclude = [
+    "tests/.*"
+]
+
+[tool.pytest.ini_options]
+markers = [
+    "docker: marks tests that require Docker (deselect with '-m \"not docker\"')",
+]
+
+[tool.ruff.lint]
+extend-select = [
+    "ARG",  # flake8-unused-arguments
+    "DTZ",  # flake8-datetimez
+    "FAST", # FastAPI
+    "I",    # isort
+    "RUF",  # Ruff-specific rules
+    "T20",  # flake8-print
+    "UP",   # pyupgrade
+]
+
+[tool.ruff.lint.per-file-ignores]
+"examples/**.py" = [
+    "T20",  # flake8-print
+]
+
+[tool.ty.src]
+exclude = [
+    "checkmk-integration/watchpost-plugin/",
+    "tests/",
+]

watchpost-0.1.0/src/watchpost/__init__.py

@@ -0,0 +1,71 @@
+# Copyright 2025 TAKKT Industrial & Packaging GmbH
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from .app import Watchpost
+from .cache import Cache, ChainedStorage, DiskStorage, InMemoryStorage, RedisStorage
+from .check import CheckFunctionResult, check
+from .datasource import (
+    Datasource,
+    DatasourceFactory,
+    DatasourceUnavailable,
+    FromFactory,
+)
+from .environment import Environment, EnvironmentRegistry
+from .globals import current_app
+from .result import (
+    CheckResult,
+    Metric,
+    Thresholds,
+    build_result,
+    crit,
+    ok,
+    unknown,
+    warn,
+)
+from .scheduling_strategy import (
+    MustRunAgainstGivenTargetEnvironmentStrategy,
+    MustRunInGivenExecutionEnvironmentStrategy,
+    MustRunInTargetEnvironmentStrategy,
+)
+
+__all__ = [
+    "Cache",
+    "ChainedStorage",
+    "CheckFunctionResult",
+    "CheckResult",
+    "Datasource",
+    "DatasourceFactory",
+    "DatasourceUnavailable",
+    "DiskStorage",
+    "Environment",
+    "EnvironmentRegistry",
+    "FromFactory",
+    "InMemoryStorage",
+    "Metric",
+    "MustRunAgainstGivenTargetEnvironmentStrategy",
+    "MustRunInGivenExecutionEnvironmentStrategy",
+    "MustRunInTargetEnvironmentStrategy",
+    "RedisStorage",
+    "Thresholds",
+    "Watchpost",
+    "build_result",
+    "check",
+    "crit",
+    "current_app",
+    "ok",
+    "unknown",
+    "warn",
+]