{"id":8055,"library":"cysignals","title":"cysignals","description":"cysignals is a Python library designed for robust interrupt and signal handling within Cython code. It provides mechanisms to ensure that long-running Cython computations can be interrupted (e.g., via CTRL-C) and offers a Python interface for managing OS-level signal handlers and system calls like `pselect()` and `sigprocmask()`. The library is currently at version 1.12.6, actively maintained by the SageMath community, and receives regular updates to support newer Python and Cython versions.","status":"active","version":"1.12.6","language":"python","source_language":"en","source_url":"https://github.com/sagemath/cysignals","tags":["cython","signals","interrupts","error-handling","sagemath"],"install":[{"cmd":"pip install cysignals","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Requires Python 3.12 or newer for current versions.","package":"python","optional":false},{"reason":"Used for compiling Cython extensions; requires Cython 3.1 or newer.","package":"cython","optional":false},{"reason":"Python build backend (PEP 517) used in the build process.","package":"meson-python","optional":true}],"imports":[{"wrong":"from cysignals.signals cimport sig_check","symbol":"AlarmInterrupt","correct":"from cysignals import AlarmInterrupt"},{"symbol":"SignalError","correct":"from cysignals import SignalError"},{"symbol":"init_cysignals","correct":"from cysignals import init_cysignals"}],"quickstart":{"code":"import cython\nimport os\n\n# This code needs to be in a .pyx file to be compiled by Cython\n# For demonstration, we simulate compilation by directly defining in Python context\n# In a real scenario, this would be compiled with a setup.py/pyproject.toml\n\ndef run_interruptible_loop(n_iterations: int):\n    try:\n        # In a .pyx file, you would use: from cysignals.signals cimport sig_check\n        # For this quickstart, we use a mock for illustration in a .py file\n        # In practice, you'd compile this Cython code.\n        # This is a simplified representation of how sig_check would be used.\n\n        # Simulate Cython compilation and execution\n        print(f\"Running a loop for {n_iterations} iterations. Try pressing CTRL+C.\")\n        for i in range(n_iterations):\n            # Imagine this is within a Cython function containing a `sig_check()` call\n            if i % 1_000_000 == 0:\n                print(f\"  Iteration {i}\")\n            # A real sig_check() would check for interrupts and raise KeyboardInterrupt\n            # if os.getenv('CYSIGNALS_SIMULATE_INTERRUPT') and i == n_iterations // 2:\n            #     raise KeyboardInterrupt(\"Simulated interrupt\")\n            \n            # Simulate a small amount of work\n            _ = i * i\n\n        print(\"Loop completed without interruption.\")\n\n    except KeyboardInterrupt:\n        print(\"\\nLoop interrupted by user (KeyboardInterrupt caught)!\")\n    except Exception as e:\n        print(f\"An unexpected error occurred: {e}\")\n\nif __name__ == '__main__':\n    # This part would run the compiled Cython module\n    # For this example, we directly call the Python function simulating the loop.\n    run_interruptible_loop(10_000_000)","lang":"python","description":"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."},"warnings":[{"fix":"Review `cysignals` documentation for alternative error handling mechanisms if relying on C library callbacks. If `_pari_version` was used, it now returns `None`.","message":"cysignals 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.","severity":"breaking","affected_versions":">=1.12.0"},{"fix":"Upgrade 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).","message":"Version 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.","severity":"breaking","affected_versions":">=1.12.6, >=1.11.0"},{"fix":"Ensure `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.","message":"When 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure `_FORTIFY_SOURCE` is not defined or is set to `0` during compilation of `cysignals` and modules linking against it. This typically involves adjusting CFLAGS.","message":"Compiling cysignals with `_FORTIFY_SOURCE` enabled can lead to compilation errors.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure 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.","message":"The 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.","severity":"deprecated","affected_versions":">=1.12.0"}],"env_vars":null,"search_vec":"'1.12.6':61 'activ':62 'c':35 'call':50 'code':16 'communiti':67 'comput':27 'ctrl':34 'ctrl-c':33 'current':58 'cysign':1,2 'cython':15,26,77,79 'design':7 'e.g':31 'ensur':21 'error':83 'error-handl':82 'handl':13,84 'handler':47 'interfac':40 'interrupt':10,30,81 'level':45 'librari':6,56 'like':51 'long':24 'long-run':23 'maintain':63 'manag':42 'mechan':19 'newer':74 'offer':37 'os':44 'os-level':43 'provid':18 'pselect':52 'python':5,39,75 'receiv':69 'regular':70 'robust':9 'run':25 'sagemath':66,85 'signal':12,46,80 'sigprocmask':54 'support':73 'system':49 'updat':71 'version':60,78 'via':32 'within':14","created_at":"2026-04-16T17:00:11.694061+00:00","updated_at":"2026-04-16T17:00:11.694061+00:00","problems":null,"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"1.12.6","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/sagemath/cysignals","docs":null,"changelog":null,"pypi":"https://pypi.org/project/cysignals/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["devops","http-networking"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-30","last_verified":"2026-06-30","next_check":"2026-07-30","install_tag":null}}