Install & Compatibility
Where this runs
tested against v1.12.5 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.000s · 18.6MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 1.6s · import 0.000s · 19MB
17MB installed
● package 17MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
AlarmInterrupt
✓ from cysignals import AlarmInterrupt
✗ from cysignals.signals cimport sig_check
SignalError
✓ from cysignals import SignalError
init_cysignals
✓ from cysignals import init_cysignals
This quickstart demonstrates the core interrupt handling mechanism using `sig_check()`. While `sig_check()` is a Cython cimport, the Python code here illustrates its effect by demonstrating an interruptible long-running loop. In actual use, `sig_check()` would be placed within Cython `def`, `cdef`, or `cpdef` functions to allow graceful interruption. A real-world example would involve compiling a `.pyx` file containing the `cimport` and `sig_check()` calls.
import cython
import os
# This code needs to be in a .pyx file to be compiled by Cython
# For demonstration, we simulate compilation by directly defining in Python context
# In a real scenario, this would be compiled with a setup.py/pyproject.toml
def run_interruptible_loop(n_iterations: int):
try:
# In a .pyx file, you would use: from cysignals.signals cimport sig_check
# For this quickstart, we use a mock for illustration in a .py file
# In practice, you'd compile this Cython code.
# This is a simplified representation of how sig_check would be used.
# Simulate Cython compilation and execution
print(f"Running a loop for {n_iterations} iterations. Try pressing CTRL+C.")
for i in range(n_iterations):
# Imagine this is within a Cython function containing a `sig_check()` call
if i % 1_000_000 == 0:
print(f" Iteration {i}")
# A real sig_check() would check for interrupts and raise KeyboardInterrupt
# if os.getenv('CYSIGNALS_SIMULATE_INTERRUPT') and i == n_iterations // 2:
# raise KeyboardInterrupt("Simulated interrupt")
# Simulate a small amount of work
_ = i * i
print("Loop completed without interruption.")
except KeyboardInterrupt:
print("\nLoop interrupted by user (KeyboardInterrupt caught)!")
except Exception as e:
print(f"An unexpected error occurred: {e}")
if __name__ == '__main__':
# This part would run the compiled Cython module
# For this example, we directly call the Python function simulating the loop.
run_interruptible_loop(10_000_000)
Debug
Known issues
breakingcysignals versions 1.12.0 and later removed the optional compile-time dependency on PARI/GP. If your Cython code relied on the `_pari_version` function or the `sig_error()` mechanism for PARI, you will need to adjust your build process or error handling.fixReview `cysignals` documentation for alternative error handling mechanisms if relying on C library callbacks. If `_pari_version` was used, it now returns `None`.
affects: >=1.12.0
breakingVersion 1.12.6 dropped support for older Python versions, now requiring Python 3.12 or newer. Previous versions (e.g., 1.11.0) similarly dropped Python 2 support and bumped the minimum to 3.6.fixUpgrade your Python environment to 3.12 or newer. If you need to support older Python versions, you must use an older cysignals release compatible with your Python version (e.g., 1.11.3 for Python 3.12 support).
affects: >=1.12.6, >=1.11.0
gotchaWhen using `sig_on()` and `sig_off()` in Cython, they must always be called in pairs, and `sig_off()` must be executed before the function calling `sig_on()` returns (including all return or raise paths). The code within `sig_on()` and `sig_off()` should be pure C or Cython, as calling Python code or manipulating Python objects can lead to corrupted internal state if an interrupt occurs. Use `sig_check()` if you are unsure.fixEnsure `sig_on()` and `sig_off()` form a correct pair within a single function's execution path. Avoid Python API calls inside the `sig_on()` block. Prefer `sig_check()` for mixed Python/Cython loops.
affects: All versions
gotchaCompiling cysignals with `_FORTIFY_SOURCE` enabled can lead to compilation errors.fixEnsure `_FORTIFY_SOURCE` is not defined or is set to `0` during compilation of `cysignals` and modules linking against it. This typically involves adjusting CFLAGS.
affects: All versions
deprecatedThe build system for cysignals transitioned to Meson in version 1.12.0. Older `setuptools`-based build practices might encounter issues with newer `cysignals` versions or Python packaging tooling.fixEnsure your build environment is configured to use Meson. If encountering `setuptools`-related build errors, consider upgrading your packaging tools or reviewing your build configuration to align with Meson.
affects: >=1.12.0
Upgrade
Version history
1.12.6latest on PyPI · released Oct 30, 2025
Audit
Dependencies
pythonrequiredRequires Python 3.12 or newer for current versions.
cythonrequiredUsed for compiling Cython extensions; requires Cython 3.1 or newer.
meson-pythonoptionalPython build backend (PEP 517) used in the build process.