multidog 0.1.0a1__tar.gz

multidog-0.1.0a1/.editorconfig

@@ -0,0 +1,26 @@
+# SPDX-FileCopyrightText: © 2026 scy
+#
+# SPDX-License-Identifier: MIT
+
+[*]
+end_of_line = lf
+insert_final_newline = true
+charset = utf-8
+trim_trailing_whitespace = true
+
+[*.{bash,sh}]
+indent_style = tab
+
+[*.{css,html,js,json,md,scss,ts,yaml}]
+indent_size = 2
+indent_style = space
+
+[*.{py,toml}]
+indent_size = 4
+indent_style = space
+
+[*.py]
+max_line_length = 79
+
+[Makefile]
+indent_style = tab

multidog-0.1.0a1/.gitignore

@@ -0,0 +1,13 @@
+# SPDX-FileCopyrightText: © 2026 scy
+#
+# SPDX-License-Identifier: MIT
+
+/.envrc
+
+__pycache__/
+*.egg-info/
+
+/.coverage
+/coverage.lcov
+/coverage.xml
+/report.xml

multidog-0.1.0a1/LICENSES/MIT.txt

@@ -0,0 +1,18 @@
+MIT License
+
+Copyright (c) <year> <copyright holders>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and
+associated documentation files (the "Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the
+following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial
+portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT
+LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO
+EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
+USE OR OTHER DEALINGS IN THE SOFTWARE.

multidog-0.1.0a1/Makefile

@@ -0,0 +1,29 @@
+# SPDX-FileCopyrightText: © 2026 scy
+#
+# SPDX-License-Identifier: MIT
+
+.PHONY: all fmt noqa qa test reuse
+
+
+all: fmt qa reuse test
+
+
+fmt:
+	ruff format
+	ruff check --fix
+
+
+noqa:
+	ruff check --add-noqa
+
+
+qa:
+	mypy
+
+
+reuse:
+	reuse lint --lines
+
+
+test:
+	pytest

multidog-0.1.0a1/PKG-INFO

@@ -0,0 +1,164 @@
+Metadata-Version: 2.4
+Name: multidog
+Version: 0.1.0a1
+Summary: A SIGALRM-based watchdog that can handle multiple timeouts.
+Project-URL: Source, https://codeberg.org/scy/multidog
+Project-URL: Documentation, https://codeberg.org/scy/multidog
+Project-URL: Issues, https://codeberg.org/scy/multidog/issues
+Author: scy
+Maintainer: scy
+License-Expression: MIT
+License-File: LICENSES/MIT.txt
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: <4,>=3.12
+Description-Content-Type: text/markdown
+
+<!--
+SPDX-FileCopyrightText: © 2026 scy
+
+SPDX-License-Identifier: MIT
+-->
+
+# Multidog
+
+_A SIGALRM-based watchdog that can handle multiple timeouts._
+
+➡️ **Quick Links:** [Repository](https://codeberg.org/scy/multidog) · [Issues](https://codeberg.org/scy/multidog/issues)
+
+Multidog works by keeping track of one or more timeouts and setting up an [`alarm`](https://docs.python.org/3/library/signal.html#signal.alarm) signal that will cause the OS to terminate your process when the timeout occurs.
+
+
+## 🌱 Status
+
+Multidog has recently been extracted from another project of mine.
+It kind of works, but I still have to fix some issues.
+
+Things that are not yet implemented:
+
+- [ ] Timeouts are only checked with the granularity of the shortest timeout. See the example below for what this means.
+- [ ] You may only use one running instance of Multidog per process, because a process can only have one handler per signal. There is no safeguard against this at the moment.
+- [ ] Adding more timeouts after creating the `Multidog` instance is not possible yet.
+
+
+## 📚 Usage
+
+Example usage:
+
+```python
+from time import sleep
+from multidog import Multidog
+
+dog = Multidog({"a": 5, "b": 10})
+
+dog.start()
+# This will call `sys.exit()` in 5 seconds unless you reset the timeouts regularly.
+
+sleep(4)
+dog.reset("a")
+# `sys.exit()` will be deferred for another 5 seconds.
+
+sleep(4)
+dog.reset("a")
+# `sys.exit()` will be deferred for another 5 seconds.
+# This is a bug actually: The "b" timeout has never been reset and only has two
+# seconds left. Multidog should defer for only 2 seconds, but right now it doesn't.
+
+sleep(4)
+dog.reset("a")
+# Multidog finally notices that "b" is overdue and will refuse to reset the alarm,
+# causing your application to exit in one second.
+
+dog.stop()
+# Stops the watchdog before it kills your app.
+```
+
+### Anonymous timeout
+
+If you only have a single timeout to track, you can simplify your usage:
+
+```python
+dog = Multidog(5)  # equivalent to Multidog({"": 5})
+dog.start()
+dog.reset()  # equivalent to dog.reset("")
+```
+
+### Exit timeout
+
+Your Python application might not shut down fast enough (or at all) on [`sys.exit()`](https://docs.python.org/3/library/sys.html#sys.exit) (because yeah, that's something that can be suppressed).
+Therefore, Multidog will set up a second `SIGALRM` after calling `sys.exit()`, with the signal handler reset to the default, which _should_ kill your process when the timeout expires.
+
+The default timeout for this is 5 seconds, you can choose a different one like so:
+
+```python
+dog = Multidog({"a": 5, "b": 10}, exit_timeout=120)
+```
+
+
+## 🗃️ Installation
+
+Simply install the `multidog` package from PyPI via your preferred package manager.
+
+For example, to add it as a dependency to your [uv](https://docs.astral.sh/uv/)-managed project, use this:
+
+```sh
+uv add multidog
+```
+
+
+## 🧑‍💻 Development
+
+### Preparation
+
+We're using [uv](https://docs.astral.sh/uv/) to manage this project and its dependencies.
+After cloning the repository using Git, a simple `uv sync` should get everything you need.
+
+```sh
+git clone https://codeberg.org/scy/multidog.git multidog
+cd multidog
+uv sync
+```
+
+### direnv
+
+We recommend using [direnv](https://direnv.net/) to add installed dependencies to your `$PATH`, so that you don't need to prepend `uv run` to every command.
+For example, after installing direnv, you can use `direnv edit` in this repository's directory and add the following line:
+
+```sh
+PATH_add .venv/bin
+```
+
+**The rest of this readme assumes that you have `.venv/bin` in your `$PATH`.**
+
+### EditorConfig
+
+Make sure your editor or IDE supports the [EditorConfig](https://editorconfig.org/) standard, so that your code adheres to the project's [preferred](.editorconfig) indentation, line lengths, etc.
+
+### Makefile
+
+There is a [`Makefile`](Makefile) that contains frequently used commands to speed up development, but it's optional to use.
+The following targets exist:
+
+- `fmt`: Use [Ruff](https://docs.astral.sh/ruff/) to format and lint the code.
+- `qa`: Use [mypy](https://mypy.readthedocs.io/) for static type analysis.
+- `reuse`: Use [`reuse lint`](https://codeberg.org/fsfe/reuse-tool) to make sure every file contains licensing information.
+- `test`: Use [pytest](https://pytest.org/) for automated testing and code coverage.
+- `noqa`: Add `noqa` statements to ignore everything Ruff complains about. Only use this after fixing everything that needs fixing.
+
+`make all`, or simply `make`, will run `fmt`, `qa`, `reuse`, and `test`.
+You should do this before every commit and fix all issues that are reported.
+
+
+## 📃 License
+
+This project is licensed under the terms of the [MIT License](https://spdx.org/licenses/MIT.html).
+
+The project also conforms to the [REUSE Specification, version 3.3](https://reuse.software/spec-3.3/).
+You can use [the `reuse` tool](https://codeberg.org/fsfe/reuse-tool) to interpret the machine-readable licensing information.

multidog-0.1.0a1/README.md

@@ -0,0 +1,141 @@
+<!--
+SPDX-FileCopyrightText: © 2026 scy
+
+SPDX-License-Identifier: MIT
+-->
+
+# Multidog
+
+_A SIGALRM-based watchdog that can handle multiple timeouts._
+
+➡️ **Quick Links:** [Repository](https://codeberg.org/scy/multidog) · [Issues](https://codeberg.org/scy/multidog/issues)
+
+Multidog works by keeping track of one or more timeouts and setting up an [`alarm`](https://docs.python.org/3/library/signal.html#signal.alarm) signal that will cause the OS to terminate your process when the timeout occurs.
+
+
+## 🌱 Status
+
+Multidog has recently been extracted from another project of mine.
+It kind of works, but I still have to fix some issues.
+
+Things that are not yet implemented:
+
+- [ ] Timeouts are only checked with the granularity of the shortest timeout. See the example below for what this means.
+- [ ] You may only use one running instance of Multidog per process, because a process can only have one handler per signal. There is no safeguard against this at the moment.
+- [ ] Adding more timeouts after creating the `Multidog` instance is not possible yet.
+
+
+## 📚 Usage
+
+Example usage:
+
+```python
+from time import sleep
+from multidog import Multidog
+
+dog = Multidog({"a": 5, "b": 10})
+
+dog.start()
+# This will call `sys.exit()` in 5 seconds unless you reset the timeouts regularly.
+
+sleep(4)
+dog.reset("a")
+# `sys.exit()` will be deferred for another 5 seconds.
+
+sleep(4)
+dog.reset("a")
+# `sys.exit()` will be deferred for another 5 seconds.
+# This is a bug actually: The "b" timeout has never been reset and only has two
+# seconds left. Multidog should defer for only 2 seconds, but right now it doesn't.
+
+sleep(4)
+dog.reset("a")
+# Multidog finally notices that "b" is overdue and will refuse to reset the alarm,
+# causing your application to exit in one second.
+
+dog.stop()
+# Stops the watchdog before it kills your app.
+```
+
+### Anonymous timeout
+
+If you only have a single timeout to track, you can simplify your usage:
+
+```python
+dog = Multidog(5)  # equivalent to Multidog({"": 5})
+dog.start()
+dog.reset()  # equivalent to dog.reset("")
+```
+
+### Exit timeout
+
+Your Python application might not shut down fast enough (or at all) on [`sys.exit()`](https://docs.python.org/3/library/sys.html#sys.exit) (because yeah, that's something that can be suppressed).
+Therefore, Multidog will set up a second `SIGALRM` after calling `sys.exit()`, with the signal handler reset to the default, which _should_ kill your process when the timeout expires.
+
+The default timeout for this is 5 seconds, you can choose a different one like so:
+
+```python
+dog = Multidog({"a": 5, "b": 10}, exit_timeout=120)
+```
+
+
+## 🗃️ Installation
+
+Simply install the `multidog` package from PyPI via your preferred package manager.
+
+For example, to add it as a dependency to your [uv](https://docs.astral.sh/uv/)-managed project, use this:
+
+```sh
+uv add multidog
+```
+
+
+## 🧑‍💻 Development
+
+### Preparation
+
+We're using [uv](https://docs.astral.sh/uv/) to manage this project and its dependencies.
+After cloning the repository using Git, a simple `uv sync` should get everything you need.
+
+```sh
+git clone https://codeberg.org/scy/multidog.git multidog
+cd multidog
+uv sync
+```
+
+### direnv
+
+We recommend using [direnv](https://direnv.net/) to add installed dependencies to your `$PATH`, so that you don't need to prepend `uv run` to every command.
+For example, after installing direnv, you can use `direnv edit` in this repository's directory and add the following line:
+
+```sh
+PATH_add .venv/bin
+```
+
+**The rest of this readme assumes that you have `.venv/bin` in your `$PATH`.**
+
+### EditorConfig
+
+Make sure your editor or IDE supports the [EditorConfig](https://editorconfig.org/) standard, so that your code adheres to the project's [preferred](.editorconfig) indentation, line lengths, etc.
+
+### Makefile
+
+There is a [`Makefile`](Makefile) that contains frequently used commands to speed up development, but it's optional to use.
+The following targets exist:
+
+- `fmt`: Use [Ruff](https://docs.astral.sh/ruff/) to format and lint the code.
+- `qa`: Use [mypy](https://mypy.readthedocs.io/) for static type analysis.
+- `reuse`: Use [`reuse lint`](https://codeberg.org/fsfe/reuse-tool) to make sure every file contains licensing information.
+- `test`: Use [pytest](https://pytest.org/) for automated testing and code coverage.
+- `noqa`: Add `noqa` statements to ignore everything Ruff complains about. Only use this after fixing everything that needs fixing.
+
+`make all`, or simply `make`, will run `fmt`, `qa`, `reuse`, and `test`.
+You should do this before every commit and fix all issues that are reported.
+
+
+## 📃 License
+
+This project is licensed under the terms of the [MIT License](https://spdx.org/licenses/MIT.html).
+
+The project also conforms to the [REUSE Specification, version 3.3](https://reuse.software/spec-3.3/).
+You can use [the `reuse` tool](https://codeberg.org/fsfe/reuse-tool) to interpret the machine-readable licensing information.

multidog-0.1.0a1/REUSE.toml

@@ -0,0 +1,9 @@
+version = 1
+
+# Generated files.
+[[annotations]]
+path = [
+	"uv.lock",
+]
+"SPDX-FileCopyrightText" = "NONE"
+"SPDX-License-Identifier" = "MIT"

multidog-0.1.0a1/multidog/__init__.py

@@ -0,0 +1,121 @@
+# SPDX-FileCopyrightText: © 2026 scy
+#
+# SPDX-License-Identifier: MIT
+
+import logging
+import signal
+import sys
+from collections.abc import Callable, Mapping
+from datetime import UTC, datetime, timedelta
+from importlib import metadata
+
+
+PKG_NAME = "multidog"
+PROJECT_URL = "https://codeberg.org/scy/multidog"
+
+__version__ = metadata.version(PKG_NAME)
+
+
+_log = logging.getLogger(__name__)
+
+
+Timeout = timedelta | int
+
+
+class Multidog:
+    def __init__(
+        self,
+        timeout: Mapping[str, Timeout] | Timeout,
+        *,
+        exit_timeout: Timeout = 5,
+    ) -> None:
+        # Create our dict of timeouts. If we just got a single timeout value,
+        # use the empty string as its name.
+        self._timeouts = (
+            {name: self.to_timedelta(v) for name, v in timeout.items()}
+            if isinstance(timeout, Mapping)
+            else {"": self.to_timedelta(timeout)}
+        )
+
+        self._exit_timeout = self.to_timedelta(exit_timeout)
+        self._reset_all()
+
+    def _alarm(self, _signal, _stack) -> None:
+        _log.critical("watchdog timeout, shutting down")
+
+        # Remove existing signal handler and schedule another alarm that will
+        # kill us if for some reason the sys.exit() doesn't work.
+        signal.signal(signal.SIGALRM, signal.SIG_DFL)
+        signal.alarm(int(self._exit_timeout.total_seconds()))
+
+        sys.exit(128 + signal.SIGALRM)
+
+    def _reset_all(self) -> None:
+        """Reset all timers to now, i.e. not yet expired."""
+        now = datetime.now(UTC)
+        self._resets = dict.fromkeys(self._timeouts, now)
+
+    @staticmethod
+    def to_timedelta(timeout: Timeout) -> timedelta:
+        if isinstance(timeout, int):
+            return timedelta(seconds=timeout)
+        if isinstance(timeout, timedelta):
+            return timeout
+        raise TypeError(f"invalid timeout type: {type(timeout)}")
+
+    def alarm_interval(self) -> int:
+        """Return the number of seconds of the shortest configured timeout."""
+        return min(
+            int(timeout.total_seconds()) for timeout in self._timeouts.values()
+        )
+
+    def reset(self, key: str = "") -> bool:
+        """Reset the given timeout."""
+        now = datetime.now(UTC)
+        if key not in self._timeouts:
+            raise KeyError(f"unknown watchdog key: {key}")
+        self._resets[key] = now
+
+        # If one of the configured timers has not been reset in its expected
+        # time frame, we don't reset the alarm just yet. In other words, all
+        # expected timers need to have been reset before their timeout for us
+        # to reset the alarm signal and thus not get killed.
+        if any(
+            name
+            for name, timeout in self._timeouts.items()
+            if now > self._resets[name] + timeout
+        ):
+            _log.debug(
+                "not resetting watchdog, some expected resets are missing"
+            )
+            return False
+
+        _log.debug("resetting watchdog")
+        signal.alarm(self.alarm_interval())
+        return True
+
+    def resetfunc(self, key: str = "") -> Callable[[], bool]:
+        """Get a function to reset the given timeout."""
+
+        def reset_func() -> bool:
+            return self.reset(key)
+
+        return reset_func
+
+    def start(self) -> None:
+        """Start watchdog operation."""
+        # Reset all timers.
+        self._reset_all()
+        # Set our signal handler.
+        signal.signal(signal.SIGALRM, self._alarm)
+        # Have the signal fire when the shortest timeout has been reached.
+        signal.alarm(self.alarm_interval())
+
+    def stop(self) -> None:
+        """Stop watchdog operation."""
+        # Disable the signal.
+        signal.alarm(0)
+        # Reset all timers.
+        self._reset_all()
+        # Restore the default signal handler.
+        signal.signal(signal.SIGALRM, signal.SIG_DFL)

multidog-0.1.0a1/pyproject.toml

@@ -0,0 +1,144 @@
+# SPDX-FileCopyrightText: © 2026 scy
+#
+# SPDX-License-Identifier: MIT
+
+[project]
+name = "multidog"
+version = "0.1.0a1"
+description = "A SIGALRM-based watchdog that can handle multiple timeouts."
+readme = "README.md"
+requires-python = ">=3.12,<4"
+license = "MIT"
+license-files = ["LICENSES/*.txt"]
+authors = [
+    {name = "scy"},
+]
+maintainers = [
+    {name = "scy"},
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Operating System :: POSIX",
+    "Intended Audience :: Developers",
+    "Typing :: Typed",
+]
+dependencies = [
+]
+
+[project.urls]
+Source = "https://codeberg.org/scy/multidog"
+Documentation = "https://codeberg.org/scy/multidog"
+Issues = "https://codeberg.org/scy/multidog/issues"
+
+[dependency-groups]
+dev = [
+    "mypy>=1.19",
+    "pytest>=9",
+    "pytest-cov>=7",
+    "reuse>=6.2",
+    "ruff<=0.15.6",  # last version before Astral joined OpenAI
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.uv]
+package = true
+
+[tool.mypy]
+packages = [
+    "multidog",
+    "tests",
+]
+python_version = "3.12"
+warn_return_any = true
+
+[tool.pytest]
+addopts = [
+    "--strict-markers",
+    "--junit-xml=report.xml",
+    "--cov-report=term",
+    "--cov-report=lcov",
+    "--cov-report=xml",
+    "--cov=multidog",
+]
+
+[tool.ruff]
+line-length = 79
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+
+[tool.ruff.lint]
+preview = true
+select = [
+    "ANN",     # flake8-annotations
+    "ARG",     # flake8-unused-arguments
+    "ASYNC",   # flake8-async
+    "B",       # flake8-bugbear
+    "C4",      # flake8-comprehensions
+    "C90",     # mccabe complexity
+    "DTZ",     # flake8-datetimez (naive datetimes)
+    "E",       # pycodestyle errors
+    "ERA",     # eradicate (commented-out code)
+    "EXE",     # flake8-executable (shebang lines)
+    "F",       # pyflakes
+    "FA",      # flake8-future-annotations
+    "FURB",    # refurb
+    "I",       # isort
+    "INP",     # flake8-no-pep420 (implicit namespace package)
+    "ISC",     # flake8-implicit-str-concat
+    "LOG",     # flake8-logging
+    "N",       # pep8-naming
+    "PL",      # pylint
+    "PT",      # flake8-pytest-style
+    "PTH",     # flake8-use-pathlib
+    "Q",       # flake8-quotes
+    "RET",     # flake8-return
+    "RSE",     # flake8-raise
+    "RUF",     # Ruff-specific rules
+    "S",       # flake8-bandit (security)
+    "SIM",     # flake8-simplify
+    "SLF",     # flake8-self (private member access)
+    "SLOT",    # flake8-slots
+    "TCH",     # flake8-type-checking
+    "TRY",     # tryceratops
+    "T20",     # flake8-print
+    "UP",      # pyupgrade
+    "W",       # pycodestyle warnings
+]
+ignore = [
+    "C408",     # micro-optimization; I'd rather get rid of too many quotes and use dict(x=…)
+    "ISC001",   # conflict w/ formatter, see https://github.com/astral-sh/ruff/issues/8272
+    "PLC0415",  # forbids dynamic imports
+    "RUF067",   # disallows constants in __init__.py
+    "RUF200",   # requires a name for projects
+    "TRY003",   # complains about simple ValueError messages
+]
+allowed-confusables = [  # exceptions to RUF002, characters in docstrings
+    " ",  # non-breaking space
+]
+
+[tool.ruff.lint.flake8-annotations]
+mypy-init-return = true     # no return annotation required for __init__
+suppress-dummy-args = true  # don't require annotations for _foo variables
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*" = [
+    "ANN001",  # missing function argument annotation
+    "ANN201",  # missing return type annotation
+    "ARG001",  # unused function argument (e.g. require-only fixtures)
+    "INP001",  # implicit namespace package
+    "S101",    # use of assert
+]
+
+[tool.ruff.lint.isort]
+# Two blank lines after the imports.
+lines-after-imports = 2